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:
mangadap/config/default_plan.toml: The default plan, when not overridden by the user.
mangadap/data/tests/global_bin.toml: A plan used by a DAP unit test to analyze a datacube by binning all spaxels into a single spectrum.
mangadap/data/tests/dr17.toml: A plan that mimics the survey-level plan used to produce the MaNGA DAP products released in DR17.
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 |
---|---|---|---|---|
|
str |
|
Keyword to distinguish the assessment method. |
|
|
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 |
||
|
str |
|
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. |
|
|
bool |
True |
Boolean indicating that the wavelengths provided either using waverange or response_func_file are in vacuum (not air). |
|
|
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 |
|
|
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. |
|
|
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 |
---|---|---|---|---|
|
str |
|
Keyword used to distinguish between different spatial binning schemes. |
|
|
str |
|
The string identifier for the Galactic extinction curve to use. See |
|
|
int, float |
3.1 |
Ratio of V-band extinction to the B-V reddening. |
|
|
int, float |
1.0 |
Minimum S/N of spectra to include in any bin. |
|
|
int, float |
0.8 |
Minimum fraction of unmasked pixels in each spectrum included in any bin. |
|
|
ParSet, dict |
The spatial-binning parameters. |
||
|
Undefined |
Instance of the spatial-binning class. Needed in case binfunc is a non-static member function of the class. |
||
|
Undefined |
The spatial-binning function that determines which spectra go into each bin. |
||
|
ParSet, dict |
The spectral-stacking parameter set. |
||
|
Undefined |
Instance of spectral-stacking class to use. Needed in case stackfunc is a non-static member function of the class. |
||
|
Undefined |
The spectral-stacking function that stacks the spectra in a given bin. |
||
|
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 |
---|---|---|---|---|
|
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. |
||
|
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 |
||
|
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 |
||
|
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 |
||
|
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. |
||
|
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 |
---|---|---|---|---|
|
int, float |
The target S/N for each bin. |
||
|
ndarray, list |
The array of signal measurements for each on-sky position to bin. See |
||
|
ndarray, list |
The array of noise measurements for each on-sky position to bin. If not provided, |
||
|
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 |
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 |
---|---|---|---|---|
|
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 |
---|---|---|---|---|
|
str |
|
|
Operation to perform for the stacked spectrum. See |
|
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. |
|
|
ndarray, list |
List of measured cz velocities used to register the spectra. |
||
|
str |
|
|
Describes how to incorporate covariance into the spectral stacking. See |
|
int, float, ndarray, list |
The parameter(s) needed to perform a given method of handling the covariance. See |
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 |
---|---|---|---|---|
|
str |
|
Keyword used to distinguish between different spatial binning schemes. |
|
|
int, float |
1.0 |
Minimum S/N of spectrum to fit |
|
|
ParSet, dict |
Any additional parameters, aside from the spectra themselves, required by the fitting function. If None, uses a default pPXF fit. |
||
|
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. |
||
|
Undefined |
The function that models the spectra. If None, uses a default pPXF fit and anything provided for fitpar and fitclass are ignored! |
||
|
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 |
---|---|---|---|---|
|
ndarray, list, int, float |
0.0 |
Initial guess for the redshift (\(cz\)) of each binned spectrum. |
|
|
ndarray, list, int, float |
100.0 |
Initial guess for the velocity dispersion for each binned spectrum. |
|
|
str |
|
|
Iteration mode to use; see |
|
str, TemplateLibraryDef |
|
Keyword identifier or definition object used to build the spectral template library used during the fit. |
|
|
bool |
False |
Flag that the spectral resolution of the templates are (should be) matched to the galaxy data. |
|
|
PixelMask |
Pixel mask to include during the fitting; see |
||
|
int |
100 |
Number of pixels in the boxcar used to determine the local sigma for rejecting outliers. |
|
|
int |
1 |
The integer ratio between the velocity scale of the pixel in the galaxy data to that of the template data. |
|
|
int, float |
ppxf |
||
|
int |
8 |
ppxf |
|
|
int |
0 |
ppxf |
|
|
int |
2, 4, 6 |
2 |
ppxf |
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 |
---|---|---|---|---|
|
str |
|
Keyword to distinguish the template library. |
|
|
str |
|
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. |
|
|
int, float |
2.5 |
FWHM of the resolution element in angstroms. |
|
|
str |
Extension in the fits files with measurements of the spectral resolution as a function of wavelength. If present, this supercedes any provided FWHM. |
||
|
bool |
False |
Flag that the wavelengths of the spectra are in vacuum, not air. |
|
|
ndarray, list |
Two-element array with the starting and ending wavelengths for the valid spectral range of the templates. |
||
|
int, float |
Minimum valid flux in the template spectra. |
||
|
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 |
---|---|---|---|---|
|
str |
|
Keyword used to distinguish between different emission-line moment databases. |
|
|
int, float |
0.0 |
Minimum S/N of spectrum to analyze |
|
|
SpectralPixelMask |
Object used to mask spectral pixels |
||
|
str |
|
Either a string identifying the emission-line bandpass filter database to use, or the direct path to the parameter file defining the database |
|
|
bool |
True |
Redo the moment measurements after the emission-line modeling has been performed |
|
|
str |
|
The name of the emission line used to set the redshift of each spaxel used to set the observed wavelength of the bandpasses. |
|
|
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 |
---|---|---|---|---|
|
str |
|
Keyword used to distinguish between different emission-line moment databases. |
|
|
int, float |
0.0 |
Minimum S/N of spectrum to fit |
|
|
str |
|
Name of the emission-line moments band used to set the initial velocity guess for each spaxel. |
|
|
str |
Name of the emission-line moments band used to set the initial velocity dispersion guess for each spaxel. |
||
|
ParSet, dict |
Fitting function parameters |
||
|
Undefined |
Class used to perform the fit. |
||
|
Undefined |
Function or method that performs the fit; must be callable. |
||
|
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 |
---|---|---|---|---|
|
ndarray, list, int, float |
0.0 |
Single or per-binned-spectrum redshift to use as the initial velocity guess. |
|
|
ndarray, list, int, float |
100.0 |
Single or per-binned-spectrum velocity dispersion to use as the initial guess. |
|
|
str |
|
Either a string identifying the database of emission lines to fit, or the direct path to the parameter file defining the database |
|
|
str |
|
|
Mode used to set the instrumental dispersion of the emission-line templates. Mode options are explated by |
|
int, float |
0.0 |
Impose a minimum emission-line sigma by offsetting the nominal trend, in quadrature, to have this minimum value. |
|
|
str |
|
|
Method to use for deconstructing binned spectra into individual spaxels for emission-line fitting. See |
|
str, TemplateLibraryDef |
|
Keyword identifier or definition object used to build the spectral template library used during the fit. |
|
|
ndarray, list, int, float |
Single or per-binned-spectrum redshift of the stellar component |
||
|
ndarray, list, int, float |
Single or per-binned-spectrum velocity dispersion of the stellar component |
||
|
SpectralPixelMask |
Pixel mask to include during the fitting; see |
||
|
int |
101 |
Size of the boxcar to use when rejecting fit outliers (must be odd). |
|
|
int |
1 |
The integer ratio between the velocity scale of the pixel in the galaxy data to that of the template data. |
|
|
int |
-1 |
pPXF degree parameter setting the degree of the additive polynomials to use. |
|
|
int |
0 |
pPXF mdegree parameter setting the degree of the multiplicative polynomials to use. |
|
|
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 |
---|---|---|---|---|
|
str |
|
Keyword to distinguish the template library. |
|
|
str |
|
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. |
|
|
int, float |
2.5 |
FWHM of the resolution element in angstroms. |
|
|
str |
Extension in the fits files with measurements of the spectral resolution as a function of wavelength. If present, this supercedes any provided FWHM. |
||
|
bool |
False |
Flag that the wavelengths of the spectra are in vacuum, not air. |
|
|
ndarray, list |
Two-element array with the starting and ending wavelengths for the valid spectral range of the templates. |
||
|
int, float |
Minimum valid flux in the template spectra. |
||
|
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 |
---|---|---|---|---|
|
str |
|
Keyword used to distinguish between different spectral-index databases. |
|
|
int, float |
0.0 |
Minimum S/N of spectrum to fit |
|
|
SpectralPixelMask |
Object used to mask spectral pixels |
||
|
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. |
|
|
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. |
|
|
str |
|
Either a string identifying the absorption-line database to use, or the direct path to the parameter file defining the database |
|
|
str |
|
Either a string identifying the bandhead/color database to use, or the direct path to the parameter file defining the database |
|
|
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.