Analysis Plans

The DAP uses a toml file (parsed using tomli) to define one or more “analysis plans,” which define how the DAP will analyze the provided datacube. The toml file is used to instantiate an AnalysisPlan object and parsed using from_toml().

If no toml file is provided, the DAP uses the default parameters for all analysis, and the name of the plan is set to default; see default().

When providing a toml file with an altered analysis plan, each plan is identified by a top-level dictionary keyword. For example, you could name the plan default and provide a keyword identifier for that plan:

[default]
 key = 'HYB10-MILESHC-MASTARHC2'

The optional key keyword specifies the identifier for the plan separately from the dictionary key. If no key entry is provided, the name of the plan is the same as the top-level dictionary keyword.

If you want to apply more than one analysis plan, you can have multiple plans in a single toml file and the DAP will execute them in series. For example, the following defines two plans with separate keywords:

[plan1]
 key = 'HYB10-MILESHC-MASTARHC2'

[plan2]
 key = 'HYB10-MILESHC-MASTARSSP'

The nested components of the toml file need only provide alterations to the default parameters for each analysis module. For example, if you simply want to turn off the treatment of covariance in the reduction assessments module, you would do the following:

[default]
 key = 'myplan'

[default.rdxqa]
 covariance = false

This only alters the single provided parameter and leaves the other parameters at their default values.

Warning

The parameter sets for each analysis module have an associated keyword. These keywords are used in the name of the DAP reference files. In the example above, the user will have changed the covariance value, but the keyword of the rdxqa plan will have remained unchanged. Because the DAP will not redo analysis steps that it thinks are already complete (indicated by the presence of the reference file), this means that the change may not take effect if the reference file is present. Make sure to either change the name of the reference file when changing parameters on-the-fly, or set the overwrite keyword to true. See Execution.

Below, we specify how to alter the parameters for all of the main DAP modules and provide their default values. In addition to these details, make sure you understand how the DAP uses the key for each module and how the modules understand whether or not they’ve already been completed; see Execution.

Note

For examples of fully defined plan files, see:

Basic Reduction Assessments

Parameters guiding the basic assessments of the datacube to be analyzed are set by the ReductionAssessmentDef object. Its parameters and default values are:

Key

Type

Options

Default

Description

key

str

SNRG

Keyword to distinguish the assessment method.

waverange

ndarray, list

A two-element vector with the starting and ending wavelength within which to calculate the signal-to-noise. Mutually exclusive with response_func_file

response_func_file

str

gunn_2001_g_response.db

The name of a file that defines a response function to use for the S/N calculation. Must be a local file or distributed with the DAP source code. Expected to have two columns, with the wavelength and response efficiency. Mutually exclusive with waverange.

in_vacuum

bool

True

Boolean indicating that the wavelengths provided either using waverange or response_func_file are in vacuum (not air).

covariance

bool

True

Provide the fiducial spatial covariance. If this is False, no spatial covariance will be available for calculations that use the results of the reduction assessments. If True and a covariance matrix is available directly from the datacube, it will be used. If True and the datacube does not already provide a computed covariance matrix, one is calculated using covariance_matrix() method. WARNING: If either of these fail, the DAP will issue a warning and continue assuming no spatial covariance.

minimum_frac

int, float

0.8

Minimum fraction of unmasked pixels in a spectrum required for inclusion in the spatial covariance calculation. Note this should match the value used for the spatial-binning module.

overwrite

bool

False

If the output file already exists, redo all the calculations and overwrite it.

To toml file section used to change these parameters is .rdxqa. For example, to change the keyword identifier for the parameter set for the default plan, your toml file would include

[default.rdxqa]
 key = 'test'

This module has no nested parameter dictionaries.

Once parsed, the paramaters for the reduction assessments are kept in the rdxqa attribute of the AnalysisPlan object; see Inspecting the parameters.

Spatial Binning

Parameters guiding the spatial binning of the datacube are set by the SpatiallyBinnedSpectraDef object. Its parameters and default values are:

Key

Type

Options

Default

Description

key

str

SPX

Keyword used to distinguish between different spatial binning schemes.

galactic_reddening

str

ODonnell

The string identifier for the Galactic extinction curve to use. See valid_forms() for the available curves.

galactic_rv

int, float

3.1

Ratio of V-band extinction to the B-V reddening.

minimum_snr

int, float

1.0

Minimum S/N of spectra to include in any bin.

minimum_frac

int, float

0.8

Minimum fraction of unmasked pixels in each spectrum included in any bin.

binpar

ParSet, dict

The spatial-binning parameters.

binclass

Undefined

Instance of the spatial-binning class. Needed in case binfunc is a non-static member function of the class.

binfunc

Undefined

The spatial-binning function that determines which spectra go into each bin.

stackpar

ParSet, dict

The spectral-stacking parameter set.

stackclass

Undefined

Instance of spectral-stacking class to use. Needed in case stackfunc is a non-static member function of the class.

stackfunc

Undefined

The spectral-stacking function that stacks the spectra in a given bin.

overwrite

bool

False

If the output file already exists, redo all the calculations and overwrite it.

The toml file section used to change these parameters is .binning. For example, to change the keyword identifier for the parameter set for the default plan, your toml file would include

[default.binning]
 key = 'test'

This module has two nested parameter dictionaries, one that defines the method and parameters used for the spatial binning and one defining the parameters used for the spectral stacking.

Once parsed, the paramaters for the spatial binning are kept in the binning attribute of the AnalysisPlan object; see Inspecting the parameters.

Spatial Binning Methods

Selection of the spatial binning method is done using the spatial_method keyword in the .binning dictionary on the provided toml file. This is not listed in the table above because it is only used to set the relevant binpar, binclass, and binfunc components of the SpatiallyBinnedSpectraDef object. To change any of the spatial binning parameters, change the values in the .binning.spatial nested dictionary. For example, to change the S/N threshold for the Voronoi binning, your toml file would include:

[default.binning.spatial]
 target_snr = 10

The currently available spatial binning methods are:

Global

Selected using spatial_method = 'global', and puts all the datacube spectra into a single bin. No other parameters are defined.

Radial

Selected using spatial_method = 'radial', and bins spectra radially according to the isophotal properties provided by the datacube metadata; see populate_metadata(). The available parameters are:

Key

Type

Options

Default

Description

center

ndarray, list

A two-element array defining the center to use in the definition of the elliptical bins. This is defined as a sky-right offset in arcseconds from the nominal center of the object.

pa

int, float

Sets the position angle, defined from N through E of the major axis of the isophotal ellipse used to define the elliptical bins. Set to <0 to indicate that the value should be filled by the metadata in the reduction assessment class; see fill().

ell

int, float

Sets the ellipticity (1-b/a) of the isophotal ellipse use to define the elliptical bins. Set to <0 to indicate that the value should be filled by the metadata in the reduction assessment class; see fill().

radius_scale

int, float

Defines a scale factor to use when defining the radial bins. For example, you might want to scale to the a certain number of effective radii or physical scale in kpc. For no scale, use 1.0. Set to <0 to indicate that the value should be filled by the metadata in the reduction assessment class; see fill().

radii

ndarray, list

A three-element array defining the starting and ending radius for the bin edges and the number of bins to create. If the starting radius is -1, the inner-most radius is set to 0 when not using log bins or 0.1 arcsec when using logarithmically spaced bins. If the ending radius is -1, the outer-most radius is set by the spaxel at the largest radius.

log_step

bool

A flag that the radial bins should be a geometric series.

Voronoi

Selected using spatial_method = 'voronoi', and bins spectra using vorbin. The available parameters are:

Key

Type

Options

Default

Description

target_snr

int, float

The target S/N for each bin.

signal

ndarray, list

The array of signal measurements for each on-sky position to bin. See fill() to fill this based on the data in the reduction assessments object.

noise

ndarray, list

The array of noise measurements for each on-sky position to bin. If not provided, covar must be provided and be a full covariance matrix. See fill() to fill this based on the data in the reduction assessments object.

covar

float, ndarray, Covariance, spmatrix

Covariance matrix or calibration normalization. For the latter, the value is used to renormalize using \(n_{\rm calib} = n_{\rm nominal} (1 + \alpha\ \log\ N_{\rm bin})\), where \(N_{\rm bin}\) is the number of binned spaxels and \(\alpha\) is the value provided. See fill() to fill this based on the data in the reduction assessments object.

Square

Selected using spatial_method = 'square', and rebins spaxels to a more coarse binning with square spaxels. The available parameters are:

Key

Type

Options

Default

Description

binsz

float

Desired bin size in arcsec

Spectral Stacking Methods

There is currently only one spectral stacking method, meaning there is no spectral_method keyword expected by the main .binning dictionary. To change any of the spectral stacking parameters, change the values in the .binning.spectral nested dictionary. For example, to change the stacking operation, your toml file would include:

[default.binning.spectral]
 operation = 'sum'

The available spectral stacking parameters are:

Key

Type

Options

Default

Description

operation

str

mean, sum

mean

Operation to perform for the stacked spectrum. See SpectralStack.operation_options() for the available operation options.

register

bool

False

Flag to register the spectra by deshifting them based on their observed cz velocities. This is done before adding them based on a provided prior measurement of the velocities.

cz

ndarray, list

List of measured cz velocities used to register the spectra.

covar_mode

str

calibrate, approx_correlation, channels, wavelengths, none, full

none

Describes how to incorporate covariance into the spectral stacking. See SpectralStack.covariance_mode_options() for the available options.

covar_par

int, float, ndarray, list

The parameter(s) needed to perform a given method of handling the covariance. See SpectralStack.covariance_mode_options() for the available options.

Stellar Continuum Model (Stellar Kinematics)

Parameters guiding the stellar continuum modeling of the datacube, which is currently only used to model the stellar kinematics, are set by the StellarContinuumModelDef object. Its parameters and default values are:

Key

Type

Options

Default

Description

key

str

MILESHC

Keyword used to distinguish between different spatial binning schemes.

minimum_snr

int, float

1.0

Minimum S/N of spectrum to fit

fitpar

ParSet, dict

Any additional parameters, aside from the spectra themselves, required by the fitting function. If None, uses a default pPXF fit.

fitclass

Undefined

Instance of class object to use for the model fitting. Needed in case fitfunc is a non-static member function of a class. If None, uses a default pPXF fit.

fitfunc

Undefined

The function that models the spectra. If None, uses a default pPXF fit and anything provided for fitpar and fitclass are ignored!

overwrite

bool

False

If the output file already exists, redo all the calculations and overwrite it.

The toml file section used to change these parameters is .continuum. For example, to change the keyword identifier for the parameter set for the default plan, your toml file would include

[default.continuum]
 key = 'test'

Selection of the stellar continuum modeling method is done using the fit_method keyword in the .continuum dictionary on the provided toml file. Currently, this can only be 'ppxf', which selects the PPXFFit class to perform the modeling. The parameters that govern the modeling are set by the PPXFFitPar object. Its parameters and default values are:

Key

Type

Options

Default

Description

guess_redshift

ndarray, list, int, float

0.0

Initial guess for the redshift (\(cz\)) of each binned spectrum.

guess_dispersion

ndarray, list, int, float

100.0

Initial guess for the velocity dispersion for each binned spectrum.

iteration_mode

str

none, no_global_wrej, global_template, nonzero_templates, all_templates

nonzero_templates

Iteration mode to use; see PPXFFit.iteration_modes().

template_library

str, TemplateLibraryDef

MILESHC

Keyword identifier or definition object used to build the spectral template library used during the fit.

matched_resolution

bool

False

Flag that the spectral resolution of the templates are (should be) matched to the galaxy data.

pixelmask

PixelMask

Pixel mask to include during the fitting; see SpectralPixelMask().

reject_boxcar

int

100

Number of pixels in the boxcar used to determine the local sigma for rejecting outliers.

velscale_ratio

int

1

The integer ratio between the velocity scale of the pixel in the galaxy data to that of the template data.

bias

int, float

ppxf bias parameter used to penalize low S/N spectra toward a Gaussian LOSVD.

degree

int

8

ppxf degree parameter used to set the order of the additive polynomial to include in the fit.

mdegree

int

0

ppxf mdegree parameter used to set the order of the multiplicative polynomial to include in the fit.

moments

int

2, 4, 6

2

ppxf moments parameter used to set the number of moments of the LOSVD to fit. The DAP has not been well tested for fits that include any more than \(V\) and \(\sigma\).

Changes to these parameters must be made in the .continuum.fit section of the toml file. For example, to change the degree of the additive polynomial, your toml file should include:

[default.continuum.fit]
 degree = 10

Finally, the PPXFFit modeling approach requires a set of spectral templates. These are set using the .continuum.fit.templates section of the toml file; see Spectral Template Libraries. One can select a template library distributed with the DAP by specifying only the library keyword. For example, to specify the MILESHC library, your toml file would include:

[default.continuum.fit.templates]
 key = 'MILESHC'

However, you could also include an user-defined template library by defining all or most of the required parameters held by the TemplateLibraryDef object:

Key

Type

Options

Default

Description

key

str

MILESHC

Keyword to distinguish the template library.

file_search

str

miles_cluster/*.fits

Search pattern used to find the 1D fits spectra to include in the template library. The search string must either include the full path or be within the template directory of the DAP source distribution.

fwhm

int, float

2.5

FWHM of the resolution element in angstroms.

sres_ext

str

Extension in the fits files with measurements of the spectral resolution as a function of wavelength. If present, this supercedes any provided FWHM.

in_vacuum

bool

False

Flag that the wavelengths of the spectra are in vacuum, not air.

wave_limit

ndarray, list

Two-element array with the starting and ending wavelengths for the valid spectral range of the templates.

lower_flux_limit

int, float

Minimum valid flux in the template spectra.

log10

bool

False

Flag that the template spectra have been binned logarithmically in wavelength.

Note

The templates uses by the stellar-continuum and the emission-line fitting modules do not need to be the same.

Once parsed, the parameters for the continuum fitting are kept in the continuum attribute of the AnalysisPlan object; see Inspecting the parameters.

Non-parametric Emission-line Properties

Parameters guiding non-parametric measurements of the emission-line properties (using a moment analysis) are set by the EmissionLineMomentsDef object. Its parameters and default values are:

Key

Type

Options

Default

Description

key

str

EMOMMPL11

Keyword used to distinguish between different emission-line moment databases.

minimum_snr

int, float

0.0

Minimum S/N of spectrum to analyze

pixelmask

SpectralPixelMask

Object used to mask spectral pixels

passbands

str

ELBMPL9

Either a string identifying the emission-line bandpass filter database to use, or the direct path to the parameter file defining the database

redo_postmodeling

bool

True

Redo the moment measurements after the emission-line modeling has been performed

fit_vel_name

str

Ha-6564

The name of the emission line used to set the redshift of each spaxel used to set the observed wavelength of the bandpasses.

overwrite

bool

False

If the output file already exists, redo all the calculations and overwrite it.

The toml file section used to change these parameters is .eline_moments. For example, to change the keyword identifier for the parameter set for the default plan, your toml file would include

[default.eline_moments]
 key = 'test'

Particular attention should be given to the passbands parameter. This can either be a keyword selecting one of the emission-line bandpass databases distributed with the DAP or the filename of a new SDSS parameter file with a user-defined database; see Non-parametric Emission-Line Measurements.

Once parsed, the parameters for the emission-line moment measurements are kept in the elmom attribute of the AnalysisPlan object; see Inspecting the parameters.

Gaussian Emission-line Modeling

Parameters guiding the Gaussian emission-line modeling are set by the EmissionLineModelDef object. Its parameters and default values are:

Key

Type

Options

Default

Description

key

str

EFITMPL11SSPDB

Keyword used to distinguish between different emission-line moment databases.

minimum_snr

int, float

0.0

Minimum S/N of spectrum to fit

mom_vel_name

str

Ha-6564

Name of the emission-line moments band used to set the initial velocity guess for each spaxel.

mom_disp_name

str

Name of the emission-line moments band used to set the initial velocity dispersion guess for each spaxel.

fitpar

ParSet, dict

Fitting function parameters

fitclass

Undefined

Class used to perform the fit.

fitfunc

Undefined

Function or method that performs the fit; must be callable.

overwrite

bool

False

If the output file already exists, redo all the calculations and overwrite it.

The toml file section used to change these parameters is .eline_fits. For example, to change the keyword identifier for the parameter set for the default plan, your toml file would include

[default.eline_fits]
 key = 'test'

Selection of the emission-line modeling method is done using the fit_method keyword in the .eline_fits dictionary on the provided toml file. Currently, this can only be 'sasuke', which selects the Sasuke class to perform the modeling. The parameters that govern the modeling are set by the SasukePar object. Its parameters and default values are:

Key

Type

Options

Default

Description

guess_redshift

ndarray, list, int, float

0.0

Single or per-binned-spectrum redshift to use as the initial velocity guess.

guess_dispersion

ndarray, list, int, float

100.0

Single or per-binned-spectrum velocity dispersion to use as the initial guess.

emission_lines

str

ELPMPL11

Either a string identifying the database of emission lines to fit, or the direct path to the parameter file defining the database

etpl_line_sigma_mode

str

default, zero, offset

default

Mode used to set the instrumental dispersion of the emission-line templates. Mode options are explated by Sasuke.etpl_line_sigma_options().

etpl_line_sigma_min

int, float

0.0

Impose a minimum emission-line sigma by offsetting the nominal trend, in quadrature, to have this minimum value.

deconstruct_bins

str

ignore, nearest, binid

ignore

Method to use for deconstructing binned spectra into individual spaxels for emission-line fitting. See Sasuke.deconstruct_bin_options().

template_library

str, TemplateLibraryDef

MASTARSSP

Keyword identifier or definition object used to build the spectral template library used during the fit.

stellar_velocity

ndarray, list, int, float

Single or per-binned-spectrum redshift of the stellar component

stellar_dispersion

ndarray, list, int, float

Single or per-binned-spectrum velocity dispersion of the stellar component

pixelmask

SpectralPixelMask

Pixel mask to include during the fitting; see SpectralPixelMask().

reject_boxcar

int

101

Size of the boxcar to use when rejecting fit outliers (must be odd).

velscale_ratio

int

1

The integer ratio between the velocity scale of the pixel in the galaxy data to that of the template data.

degree

int

-1

pPXF degree parameter setting the degree of the additive polynomials to use.

mdegree

int

0

pPXF mdegree parameter setting the degree of the multiplicative polynomials to use.

reddening

int, float

pPXF reddening parameter setting the initial \(E(B-V)\) to fit, based on a Calzetti law.

Changes to these parameters must be made in the .eline_fits.fit section of the toml file. For example, to change the degree of the multiplicative polynomial, your toml file should include:

[default.eline_fits.fit]
 mdegree = 10

Particular attention should be given to the emission_lines parameter. This can either be a keyword selecting one of the emission-line databases distributed with the DAP or the filename of a new SDSS parameter file with a user-defined database; see Gaussian Emission-Line Modeling.

Once parsed, the parameters for the emission-line modeling are kept in the elfit attribute of the AnalysisPlan object; see Inspecting the parameters.

Finally, the Sasuke modeling approach requires a set of spectral templates. These are set using the .emline_fits.fit.templates section of the toml file; see Spectral Template Libraries. One can select a template library distributed with the DAP by specifying only the library keyword. For example, to specify the MASTARSSP library, your toml file would include:

[default.eline_fits.fit.templates]
 key = 'MASTARSSP'

However, you could also include an user-defined template library by defining all or most of the required parameters held by the TemplateLibraryDef object:

Key

Type

Options

Default

Description

key

str

MILESHC

Keyword to distinguish the template library.

file_search

str

miles_cluster/*.fits

Search pattern used to find the 1D fits spectra to include in the template library. The search string must either include the full path or be within the template directory of the DAP source distribution.

fwhm

int, float

2.5

FWHM of the resolution element in angstroms.

sres_ext

str

Extension in the fits files with measurements of the spectral resolution as a function of wavelength. If present, this supercedes any provided FWHM.

in_vacuum

bool

False

Flag that the wavelengths of the spectra are in vacuum, not air.

wave_limit

ndarray, list

Two-element array with the starting and ending wavelengths for the valid spectral range of the templates.

lower_flux_limit

int, float

Minimum valid flux in the template spectra.

log10

bool

False

Flag that the template spectra have been binned logarithmically in wavelength.

Note

The templates uses by the stellar-continuum and the emission-line fitting modules do not need to be the same.

Spectral Indices

Parameters guiding spectral index measurements are set by the SpectralIndicesDef object. Its parameters and default values are:

Key

Type

Options

Default

Description

key

str

INDXEN

Keyword used to distinguish between different spectral-index databases.

minimum_snr

int, float

0.0

Minimum S/N of spectrum to fit

pixelmask

SpectralPixelMask

Object used to mask spectral pixels

fwhm

int, float

-1

Resolution FWHM in angstroms at which to make the measurements. If -1, the measurements are taken at the native resolution of the observed spectra. If >0, the resolution should be larger than the observed resolution, and the observed data are convolved with a wavelength dependent Gaussian to match it to the provided FWHM.

compute_corrections

bool

True

Flag to compute velocity dispersion corrections to the measured indices, if possible. This requires the stellar kinematics results from the stellar continuum fitting.

absindex

str

EXTINDX

Either a string identifying the absorption-line database to use, or the direct path to the parameter file defining the database

bandhead

str

BHBASIC

Either a string identifying the bandhead/color database to use, or the direct path to the parameter file defining the database

overwrite

bool

False

If the output file already exists, redo all the calculations and overwrite it.

The toml file section used to change these parameters is .indices. For example, to change the keyword identifier for the parameter set for the default plan, your toml file would include

[default.indices]
 key = 'test'

Particular attention should be given to the absindex and bandhead parameters. These can either be keywords selecting one of the bandpass databases distributed with the DAP or the filename of a new SDSS parameter file with a user-defined database; see Spectral Indices.

Once parsed, the parameters for the spectral index measurements are kept in the sindx attribute of the AnalysisPlan object; see Inspecting the parameters.


Inspecting the parameters

All adjustments to the parameters used by the DAP should be made via the input toml file. However, if you’d like to directly inspect the parameters being used for each plan, you can get these by direct interaction with the AnalysisPlan object.

For example, you can read and inspect the DR17 analysis plan as follows. Assuming you’ve installed the MaNGA DAP source code is in a mangadap directory:

from mangadap.tests.util import data_test_file
from mangadap.config.analysisplan import AnalysisPlan
plan_file = data_test_file('dr17.toml')
plan = AnalysisPlan.from_toml(plan_file)

You then have access to (most of) the parameters that will be used throughout the analysis. For example:

# How many times will the datacube be analyzed?
>>> plan.nplans
4
# What are the plan keys?
>>> list(plan.keys())
dict_keys(['plan1', 'plan2', 'plan3', 'plan4'])
# What is the keyword of the reduction assessment module for the first plan
>>> plan.rdxqa['plan1']['key']
'SNRG'
# Or you can view the full parameter set
>>> plan.rdxqa['plan1']
Parameter           Value                    Default                  Type           Callable
---------------------------------------------------------------------------------------------
key                 SNRG                     SNRG                     str            False
waverange           None                     None                     ndarray, list  False
response_func_file  gunn_2001_g_response.db  gunn_2001_g_response.db  str            False
in_vacuum           True                     True                     bool           False
covariance          True                     True                     bool           False
minimum_frac        0.8                      0.8                      int, float     False
overwrite           False                    False                    bool           False
# What are the template-library parameters used for the emission-line
# fitting in the 2nd plan?
>>> plan.elfit['plan2']['fitpar']['template_library']
Parameter         Value                      Default               Type           Callable
------------------------------------------------------------------------------------------
key               MASTARSSP                  MILESHC               str            False
file_search       mastar_ssp_v1.0/*.fits.gz  miles_cluster/*.fits  str            False
fwhm              2.5                        2.5                   int, float     False
sres_ext          SRES                       None                  str            False
in_vacuum         True                       False                 bool           False
wave_limit        None                       None                  ndarray, list  False
lower_flux_limit  None                       None                  int, float     False
log10             True                       False                 bool           False
# What database is being used to define the absorption line indices?
>>> plan.sindx['plan1']['absindex']
'EXTINDX'

Note

Importantly, not all “parameters” are initially available, and some will change over the course of the DAP execution. Some parameters are “filled” as the code progresses using any fill methods (e.g., fill()) associated with the relevant parameter set. These methods use the provided data to fill in parameters that are specific to each datacube or spaxel. For example, the 'guess_redshift' for the emission-line parameters is initially set to the default (plan.elfit['plan1']['fitpar']['guess_redshift'] is 0.); however, the guess redshift is replaced by the first moment estimates from the emission-line moment analysis.