mangadap.proc.stellarcontinuummodel module

A class hierarchy that performs the stellar-continuum fitting.

class mangadap.proc.stellarcontinuummodel.StellarContinuumModel(method, binned_spectra, guess_vel, guess_sig=None, method_list=None, output_path=None, output_file=None, hardcopy=True, symlink_dir=None, tpl_hardcopy=False, overwrite=False, checksum=False, loggers=None, quiet=False)[source]

Bases: object

Class that holds the stellar-continuum model results.

Todo

Update attributes

Parameters:

method (StellarContinuumModelDef) – Object that defines the main parameters used for the stellar continuum fitting.
binned_spectra (mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra) – The binned spectra to fit. Must be able to access parent mangadap.datacube.datacube.DataCube attribute (cube).
guess_vel (float, numpy.ndarray) – A single or spectrum-dependent initial estimate of the redshift in km/s (\(cz\)).
guess_sig (float, numpy.ndarray, optional) – A single or spectrum-dependent initial estimate of the velocity dispersion in km/s. If None, default set to 100 km/s.
method_list (list, optional) – List of StellarContinuumModelDef objects that define one or more methods to use for the stellar continuum fitting. The default list is provided by the config files in the DAP source directory and compiled into this list using available_stellar_continuum_modeling_methods().
output_path (str, Path, optional) – The path for the output file. If None, the current working directory is used.
output_file (str, optional) – The name of the output “reference” file. The full path of the output file will be directory_path/output_file. If None, the default is to combine cube.output_root and the method keys. The order of the keys is the order of operations (rdxqa, binning, stellar continuum). See default_paths().
hardcopy (bool, optional) – Flag to write the HDUList attribute to disk. If False, the core astropy.io.fits.HDUList attribute (hdu) is only kept in memory and would have to be reconstructed.
symlink_dir (str, optional) – Create a symbolic link to the created file in the supplied directory. If None, no symbolic link is created.
tpl_hardcopy (bool, optional) – Save the processed template library used during the fit. If True, the output path and symlink directory for the template library are identical to the main reference file.
overwrite (bool, optional) – Overwrite any existing files. Default is to use any existing file instead of redoing the analysis and overwriting the existing output.
checksum (bool, optional) – Use the checksum in the fits header to confirm that the data has not been corrupted. The checksum is always written to the fits header when the file is created.
loggers (list, optional) – List of logging.Logger objects to log progress; ignored if quiet=True. Logging is done using mangadap.util.log.log_output(). Default is no logging.
quiet (bool, optional) – Suppress all terminal and logging output.

loggers

List of logging.Logger objects to log progress.

Type:: list

quiet

Suppress all terminal and logging output.

Type:: bool

_add_method_header(hdr)[source]

Add method-specific metadata to the header.

Note that the header object is both edited in-place and returned.

Parameters:: hdr (astropy.io.fits.Header) – Input base header for added keywords. Expected to have been initialized using _initialize_primary_header().
Returns:: Edited header object.
Return type:: astropy.io.fits.Header

_assign_image_arrays()[source]: Set image_arrays, which contains the list of extensions in hdu that are on-sky image data.

_assign_spectral_arrays()[source]: Set spectral_arrays, which contains the list of extensions in hdu that contain spectral data.

_construct_2d_hdu(good_snr, model_flux, model_mask, model_par)[source]

Construct hdu that is held in memory for manipulation of the object. See construct_3d_hdu() to convert the object into a datacube.

Parameters:

good_snr (numpy.ndarray) – Boolean array selecting the bins with good S/N.
model_flux (numpy.ndarray) – Best-fitting model spectra for each bin.
model_mask (numpy.ndarray) – Bitmask flags for each model pixel.
( (model_par) – class`~mangadap.proc.spectralfitting.StellarKinematicsFitDataTable`): Data table with the best-fitting model parameters.

_finalize_cube_mask(mask)[source]

Finalize the mask after the 2D mask has been reconstructed into a 3D cube.

This mostly handles the masks for regions outside the datacube field of view.

Note that the input mask is both edited in-place and returned.

Todo

This needs to be abstracted for non-DRP datacubes.
Describe MAPMASK usage

Parameters:: mask (numpy.ndarray) – 3D array with the current bitmask data.
Returns:: Edited bitmask data.
Return type:: numpy.ndarray

_get_missing_models(debug=False)[source]

Find the spectra with missing models, either because there is no model or the bin is also missing.

Parameters:: debug (bool, optional) – When checking the S/N limits, run mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra.above_snr_limit() in debug mode.
Returns:: Sorted list of missing models.
Return type:: numpy.ndarray

_initialize_primary_header(hdr=None)[source]

Construct the primary header for the reference file.

Parameters:: hdr (astropy.io.fits.Header, optional) – Input base header for added keywords. If None, uses the datacube header from binned_spectra (if there is one) and then cleans the header using mangadap.util.fitsutil.DAPFitsUtil.clean_dap_primary_header().
Returns:: Initialized header object.
Return type:: astropy.io.fits.Header

all_except_emission_flags()[source]

all_spectrum_flags()[source]

construct_3d_hdu()[source]: Reformat the model spectra into a cube matching the shape of the DRP fits file.

construct_models(replacement_templates=None, redshift_only=False, deredshift=False, corrected_dispersion=False)[source]

Reconstruct the best fitting models.

This is largely a wrapper for a construct_models() method provided by the method fitting class. As such, this method will raise an exception if the fitting class has no such method.

Parameters:

replacement_templates (TemplateLibrary, optional) – Instead of using the template library used to fit the data, use this library instead. The number of spectra in the replacement library must match the original number of templates. This is only really useful when replacing the original set of templates with ones at a different spectral resolution.
redshift_only (bool, optional) – When constructing the models, only redshift the spectra, effectively providing the best-fitting model with a velocity dispersion of 0 km/s.
deredshift (bool, optional) – Return the best-fitting models in the rest frame.
corrected_dispersion (bool, optional) – Return the best-fitting models with a LOSVD that has been corrected for any resolution difference between the fitted templates and the binned spectra.

Returns:

The best-fitting models.

Return type:

numpy.ndarray

Raises:

ValueError – Raised if there is no defined fitting class.
AttributeError – Raised if the fitting class has no method called construct_models().
TypeError – Raised if the provided replacement_templates are not an instance of mangadap.proc.templatelibary.TemplateLibrary.

copy_to_array(ext='FLUX', waverange=None, include_missing=False)[source]

Wrapper for mangadap.util.fitsutil.DAPFitsUtil.copy_to_array() specific for StellarContinuumModel.

Return a copy of the selected data array. The array size is always \(N_{\rm models} \times N_{\rm wavelength}\); i.e., the data is always flattened to two dimensions and the unique spectra are selected.

Parameters:

ext (str, optional) – Name of the extension from which to draw the data. Must be allowed for the current mode; see data_arrays.
waverange (array-like, optional) – Two-element array with the first and last wavelength to include in the computation. If None, use the full wavelength range.
include_missing (bool, optional) – Create an array with a size that accommodates the missing models.

Returns:

A 2D array with a copy of the data from the selected extension.

Return type:

numpy.ndarray

copy_to_masked_array(ext='FLUX', flag=None, waverange=None, include_missing=False)[source]

Wrapper for mangadap.util.fitsutil.DAPFitsUtil.copy_to_masked_array() specific for StellarContinuumModel.

Return a copy of the selected data array as a masked array. This is functionally identical to copy_to_array(), except the output format is a numpy.ma.MaskedArray. The pixels that are considered to be masked can be specified using flag.

Parameters:

ext (str, optional) – Name of the extension from which to draw the data. Must be allowed for the current mode; see data_arrays.
flag (str, list, optional) – (List of) Flag names that are considered when deciding if a pixel should be masked. The names must be a valid bit name as defined by bitmask. If not provided, ANY non-zero mask bit is omitted.
waverange (array-like, optional) – Two-element array with the first and last wavelength to include in the computation. If None, use the full wavelength range.
include_missing (bool, optional) – Create an array with a size that accommodates the missing models.

Returns:

A 2D array with a copy of the data from the selected extension.

Return type:

numpy.ma.MaskedArray

static default_paths(cube, method_key, rdxqa_method, binning_method, output_path=None, output_file=None)[source]

Set the default directory and file name for the output file.

Parameters:

cube (mangadap.datacube.datacube.DataCube) – Datacube to analyze.
method_key (str) – Keyword designating the method used for the reduction assessments.
rdxqa_method (str) – The method key for the basic assessments of the datacube.
binning_method (str) – The method key for the spatial binning.
output_path (str, Path, optional) – The path for the output file. If None, the current working directory is used.
output_file (str, optional) – The name of the output “reference” file. The full path of the output file will be directory_path/output_file. If None, the default is to combine cube.output_root and the method keys. The order of the keys is the order of operations (rdxqa, binning, stellar continuum).

Returns:

Returns a Path with the output directory and a str with the output file name.

Return type:

tuple

file_name()[source]: Return the name of the output file.

file_path()[source]: Return the full path to the output file.

fill_to_match(binid, replacement_templates=None, redshift_only=False, deredshift=False, corrected_dispersion=False, missing=None)[source]

Get the stellar-continuum model from this objects that matches the input bin ID matrix.

The output is a 2D matrix ordered by the bin ID; any skipped index numbers in the maximum of the union of the unique numbers in the binid and missing input are masked.

All this does is find the stellar continuum from spaxels in this model and match them to the input spaxels. Depending on how differently the data sets have been binned, this says nothing about whether or not the returned models are a good fit to the data!

Parameters:

binid (numpy.ndarray) – A map of the bin IDs with shape that matches the spatial shape of the parent datacube; see spatial_shape. This provides the mapping between the current stellar continuum models and the output data array.
replacement_templates (mangadap.proc.templatelibary.TemplateLibrary, optional) – Instead of using the template library used to fit the data, use this library instead. The number of spectra in the replacement library must match the original number of templates. This is only really useful when replacing the original set of templates with ones at a different spectral resolution.
redshift_only (bool, optional) – When constructing the models, only redshift the spectra, effectively providing the best-fitting model with a velocity dispersion of 0 km/s.
deredshift (bool, optional) – Return the best-fitting models in the rest frame.
corrected_dispersion (bool, optional) – Return the best-fitting models with a LOSVD that has been corrected for any resolution difference between the fitted templates and the binned spectra.
missing (array-like, optional) – Include empty spectra for binids with these numbers. Ignored if None or an empty array.

Returns:

The best-fitting models matched to the input bin ID array.

Return type:

numpy.ndarray

Raises:

ValueError – Raised if the shape of binid does not match spatial_shape.

fit(binned_spectra, guess_vel, guess_sig=None, output_path=None, output_file=None, hardcopy=True, symlink_dir=None, tpl_hardcopy=None, overwrite=None, loggers=None, quiet=False)[source]

Fit the binned spectra using the specified method.

Parameters:

binned_spectra (mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra) – The binned spectra to fit. Must be able to access parent mangadap.datacube.datacube.DataCube attribute (cube).
guess_vel (float, numpy.ndarray) – A single or spectrum-dependent initial estimate of the redshift in km/s (\(cz\)).
guess_sig (float, numpy.ndarray, optional) – A single or spectrum-dependent initial estimate of the velocity dispersion in km/s.
output_path (str, Path, optional) – The path for the output file. If None, the current working directory is used.
output_file (str, optional) – The name of the output “reference” file. The full path of the output file will be directory_path/output_file. If None, the default is to combine cube.output_root and the method keys. The order of the keys is the order of operations (rdxqa, binning, stellar continuum). See default_paths().
hardcopy (bool, optional) – Flag to write the HDUList attribute to disk. Default is True; if False, the HDUList is only kept in memory and would have to be reconstructed.
symlink_dir (str, optional) – Create a symbolic link to the created file in the supplied directory. Default is to produce no symbolic link.
tpl_hardcopy (bool, optional) – Save the processed template library used during the fit. If True, the output path and symlink directory for the template library are identical to the main reference file.
overwrite (bool, optional) – Overwrite any existing files. Default is to use any existing file instead of redoing the analysis and overwriting the existing output.
loggers (list, optional) – List of logging.Logger objects to log progress; ignored if quiet=True. Logging is done using mangadap.util.log.log_output(). Default is no logging.
quiet (bool, optional) – Suppress all terminal and logging output.

get_template_library(output_path=None, output_file=None, hardcopy=None, symlink_dir=None, velocity_offset=None, match_resolution=False, resolution_fwhm=None)[source]

Construct the template library for the continuum fitting.

If the FWHM (in angstroms; see resolution_fwhm) is not provided, this method is a simple wrapper that returns a mangadap.proc.templatelibrary.TemplateLibrary. Otherwise, the provided FWHM is used to construct the spectral resolution for the template library.

In either case, the sampling is set to match the spectra in binned_spectra (up to the velocity-scale ratio set by method).

Parameters:

output_path (str, Path, optional) – The path for the output file. If None, set to directory_path. An output file is only produced if hardcopy is True.
output_file (str, optional) – The name of the output template library file. If None and resolution_fwhm is None, uses the default template library file; see default_paths(). If None and resolution_fwhm is provided, the default template file is also used, but the library key is changed to indicate the new FHWM of the output resolution. An output file is only produced if hardcopy is True.
hardcopy (bool, optional) – Flag to keep a hardcopy of the processed template library. If None, the flag is set by tpl_hardcopy. If no hardcopy is to be produced, output_path and output_file are ignored.
symlink_dir (str, optional) – Create a symbolic link to the created template library file in this directory. If None, symlink_dir is used. A symlink is produced only if hardcopy is True.
velocity_offset (float, optional) – Velocity offset to use when matching the spectral resolution between the template library and the galaxy spectra.
match_resolution (bool, optional) – Match the spectral resolution of the template library to the resolution provided by the cube; the latter must be provided for this argument to have any use.
resolution_fwhm (float, optional) – The target resolution for the template library set by a constant FWHM of the resolution element in angstroms over all wavelengths. If None, the resolution is either matched to the binned spectra (see match_resolution) or kept at the native resolution of the library.

Returns:

The template library prepared for fitting the binned spectra.

Return type:

mangadap.proc.templatelibrary.TemplateLibrary

info()[source]

matched_kinematics(binid, redshift=None, dispersion=100.0, constant=False, cz=False, corrected=False, min_dispersion=None, nearest=False, missing=None)[source]

Get the stellar kinematics from this objects that matches the input bin ID matrix.

This method has a similar intent to fill_to_match(), but instead of matching the model spectra, its intent is to match the stellar kinematics.

For spectra the were not fit but have a bin ID (see binid), the method uses the median (unmasked) kinematic measurement if no default values are provided (see redshift and dispersion).

Parameters:

binid (numpy.ndarray) – 2D array with the bin ID associate with each spaxel in the datacube. Shape must be the same as spatial_shape.
redshift (float, optional) – The default redshift to use for spectra without a stellar-continuum fit. Default is to use the median of the unmasked measurements
dispersion (float, optional) – The default velocity dispersion to use for spectra without a stellar-continuum fit. Default is 100 km/s.
constant (bool, optional) – Force the function to return a constant redshift and dispersion for each spectrum, regardless of any fitted kinematics.
cz (bool, optional) – Return the redshift as cz in km/s, as opposed to unitless z.
corrected (bool, optional) – Return the velocity dispersions corrected for any resolution difference between the templates and the galaxy data. If False, return the uncorrected data.
min_dispersion (float, optional) – Impose a minimum dispersion.
nearest (bool, optional) – Instead of the median of the results for the spectra that were not fit, use the value from the nearest bin.
missing (array-like, optional) – Any bin ID numbers missing from the input binid image needed for constructing the output matched data.

Returns:

Returns numpy.ndarray objects with a redshift (or cz) and dispersion for each binned spectrum. Shape is \((N_{\rm bin},)\).

Return type:

tuple

Raises:

TypeError – Raised if the input redshift or dispersion values are not single numbers.
ValueError – Raised if the shape of binid does not match spatial_shape.

read(ifile=None, strict=True, checksum=False, debug=False)[source]

Read an existing file with a previously fit set of continuum models.

Parameters:

ifile (str, optional) – Name of the file with the data. Default is to use the name provided by file_path().
strict (bool, optional) – Force a strict reading of the file to make sure that it adheres to the expected format. At the moment, this only checks to make sure the method keyword printed in the header matches the expected value in method.
checksum (bool, optional) – Use the checksum in the header to check for corruption of the data.
debug (bool, optional) – Run check for missing models in debugging mode.

Raises:

FileNotFoundError – Raised if the file does not exist.
ValueError – Raised if strict is true and the header keyword SCKEY does not match the method keyword.

static reset_continuum_mask_window(continuum, dispaxis=1, quiet=False)[source]

Reset the mask of the stellar continuum to a continuous window from the minimum to maximum valid wavelength.

Todo

Allow continuum to be n-dimensional and use numpy.apply_along_axis.

Parameters:

continuum (numpy.ma.MaskedArray) – Stellar continuum models.
dispaxis (int, optional) – Wavelength axis in provided continuum object.
quiet (bool, optional) – Suppress terminal output.

Returns:

Continuum object but unmasked over the full continuous window between the minimum and maximum valid wavelength.

Return type:

numpy.ma.MaskedArray

unmasked_continuum_model(replacement_templates=None, redshift_only=False, deredshift=False, corrected_dispersion=False)[source]

Return the stellar continuum unmasked over the full continuous fitting region.

Models are reconstructed based on the model parameters if new template fluxes are provided or if the returned models should not include the LOSVD convolution (redshift_only=True). As such, this is largely a wrapper for construct_models() and reset_continuum_mask_window().

Parameters:

replacement_templates (mangadap.proc.templatelibary.TemplateLibrary, optional) – Instead of using the template library used to fit the data, use this library instead. The number of spectra in the replacement library must match the original number of templates. This is only really useful when replacing the original set of templates with ones at a different spectral resolution.
redshift_only (bool, optional) – When constructing the models, only redshift the spectra, effectively providing the best-fitting model with a velocity dispersion of 0 km/s.
deredshift (bool, optional) – Return the best-fitting models in the rest frame.
corrected_dispersion (bool, optional) – Return the best-fitting models with a LOSVD that has been corrected for any resolution difference between the fitted templates and the binned spectra.

Returns:

The best-fitting models.

Return type:

numpy.ndarray

write(match_datacube=False, overwrite=False)[source]

Write the hdu object to the file.

Parameters:

match_datacube (bool, optional) – Match the shape of the data arrays to the input datacube. I.e., convert them to 3D and replicate the binned spectrum to each spaxel in the bin.
overwrite (bool, optional) – Overwrite any existing file.

class mangadap.proc.stellarcontinuummodel.StellarContinuumModelBitMask[source]

Bases: DAPBitMask

Derived class that specifies the mask bits for the stellar-continuum modeling. The maskbits defined are:

Key	Bit	Description
DIDNOTUSE	0	Pixel was ignored because it was flagged in the binning step; see the DRPFits.do_not_stack_flags() and SpatiallyBinnedSpectra.do_not_fit_flags().
FORESTAR	1	Pixel was ignored because it was flagged as FORESTAR by the DRP.
LOW_SNR	2	Pixel was ignored because the S/N estimate of the spectrum was below the set threshold; see header keyword SCMINSN.
ARTIFACT	3	Pixel was ignored during the stellar-continuum fit because it was designated as containing an artifact.
OUTSIDE_RANGE	4	Pixel was ignored during the stellar-continuum fit because it was outside the designated spectral range of the fit; see the header keyword FITWAVE.
EML_REGION	5	Pixel was ignored during the stellar-continuum fit because it contains an emission-line.
TPL_PIXELS	6	These pixels were removed to ensure that the number of template spectral pixels was >= the number of fitted object pixels during the stellar-continuum fit.
TRUNCATED	7	This region was truncated to avoid convolution errors at the edges of the spectral range during the stellar-continuum fit.
PPXF_REJECT	8	Pixel was rejected during the pPXF fit via the clean parameter.
INVALID_ERROR	9	Pixel ignored because the flux error was invalid.
NO_FIT	10	Spectrum not fit such that not parameters are provided.
MAXITER	11	The fit optimizer reached the maximum number of iterations during the fit, which may imply failure to converge.
LARGE_CHI2	12	This pixel has a large chi^2 (definition of large TBD).
LARGE_RESID	13	This pixel has a large residual (definition of large TBD).
INSUFFICIENT_DATA	14	There were insufficient data in the fitting window to fit the line profile(s).
FIT_FAILED	15	Stellar-continuum fit failed according to status returned by scipy.optimize.least_squares.
NEAR_BOUND	16	Fit parameters are within at or near the imposed boundaries in parameter space.
NEGATIVE_WEIGHTS	17	Weights for templates were negative.
BAD_SIGMA	18	Corrected velocity dispersion is below 50 km/s or above 400 km/s
MIN_SIGMA	19	The fitted velocity dispersion is at the minimum allowed by pPXF (1/100th of a pixel)
BAD_SIGMACORR_SRES	20	The instrumental dispersion correction for the velocity dispersion, based on the quadrature difference in the spectral resolution, is invalid.
BAD_SIGMACORR_EMP	21	The instrumental dispersion correction for the velocity dispersion, based on fitting the native resolution template to the resolution matched template, is invalid.

cfg_root = 'stellar_continuum_model_bits'

class mangadap.proc.stellarcontinuummodel.StellarContinuumModelDef(key='MILESHC', minimum_snr=1.0, fitpar=None, fitclass=None, fitfunc=None, overwrite=False)[source]

Bases: KeywordParSet

A class that holds the parameters necessary to perform the stellar-continuum fitting.

The provided fitfunc must have the form:

model_wave, model_flux, model_mask, model_par                 = fitfunc(self, binned_spectra, par=None)

where binned_spectra has type mangadap.proc.spatiallybinnedspetra.SpatiallyBinnedSpectra, and the returned objects are the wavelength vector, the fitted model flux, a bitmask for the model, and the set of model parameters. For example, see mangadap.proc.ppxffit.PPXFFit.fit_SpatiallyBinnedSpectra().

The defined parameters are:

Key	Type	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.

_validate()[source]: Validate the modeling method.

classmethod from_dict(d)[source]

Instantiate the object from a nested dictionary.

The dictionary is expected to have keys for all the class keywords; see the class instantiation method. It should also include the 'fit_method' keyword used to select the type of fit to perform, and a nested dictionary selected by the keyword 'fit' with the parameters required by the fitting method. If these are not provided, the default fitter, PPXFFit and parameters will be used.

Warning

Currently, the only accepted value for 'fit_method' is 'ppxf', and the 'fit' dictionary must provide the parameters defined by PPXFFitPar.

Parameters:: d (dict) – Dictionary used to instantiate the class.