mangadap.contrib.xjmc module

Implements an emission-line fitting function using pPXF.

Revision history

31 Aug 2017: First commit by Xihan Ji (XJ)
06 Feb 2018: K. Westfall (KBW) added documentation
09 Feb 2018: (KBW) Return the bin matching vector
20 Mar 2018: (KBW) Correct error in carrying around pixels rejected during fit
22 May 2018: (KBW) Change import to ppxf package.
29 May 2018: (KBW) Remove original function from Xihan and rename *_edit function.
License

Copyright © 2019, SDSS-IV/MaNGA Pipeline Group

mangadap.contrib.xjmc._combine_stellar_templates(templates, gas_template, wgts, component, vgrp=None, sgrp=None)[source]

Reconstruct the set of templates used to fit each spectrum.

Based on an initial fit to the spectra, construct a single optimal stellar template to use for each spectrum, and combine those with the existing gas templates. Each optimal stellar-continuum template is set to the zeroth component.

Warning

  • There can only be one stellar component per fit.

  • It is possible for some optimal stellar-continuum templates to be 0 everywhere. In this case, the template is excluded from the array selecting which templates to include in the fit; however, that template is assigned a component. These details are handled by _ppxf_component_setup().

Todo

Allow for different template construct modes? E.g., use all, use anything that was non-zero in the first fit, or use single optimal template (as done now).

Parameters

  • templates (numpy.ndarray) – Templates library to use for fitting. Shape is (NTPLPIX,NTPL).

  • gas_template (numpy.ndarray) – Boolean vector that selects the gas templates. Shape is (NTPL,).

  • wgts (numpy.ndarray) – The best-fitting template weights for each template in each spectrum. Shape is (NSPEC,NTPL).

  • component (numpy.ndarray) – Integer vector identifying the kinematic component for each template. Shape is (NTPL,).

  • vgrp (array-like, optional) – The integer velocity group associated with each template. Shape is \((N_{\rm tpl},)\) , but can be None.

  • sgrp (array-like, optional) – The integer sigma group associated with each template. Shape is \((N_{\rm tpl},)\) , but can be None.

Returns

Seven arrays are returned:

  • (1) the weights of only the stellar templates used in constructing each optimal template [shape is (NSPEC,NTPL)];

  • (2) the optimal stellar templates for each spectrum with the gas templates appended [shape is (NSPEC+NGASTPL,NPIXTPL)];

  • (3) a boolean array that selects the gas templates [shape is (NSPEC+NGASTPL,);

  • (4) boolean array selecting which templates to use with each spectrum [shape is (NSPEC,NSPEC+NGASTPL)]

  • (5) integer array setting the component associated with each template [shape is (NSPEC+NGASTPL)].

  • (6) integer array setting the velocity group associated with each template [shape is (NSPEC+NGASTPL)].

  • (7) integer array setting the sigma group associated with each template [shape is (NSPEC+NGASTPL)].

Return type

tuple

Raises

ValueError – Raised if there is more than one stellar component.

mangadap.contrib.xjmc._fit_iteration(templates, wave, flux, noise, velscale, start, moments, component, gas_template, tpl_to_use=None, reject_boxcar=101, velscale_ratio=None, degree=- 1, mdegree=0, reddening=None, vgrp=None, sgrp=None, mask=None, vsyst=0, plot=False, quiet=True, sigma_rej=3.0, starting_spectrum=None)[source]

Run a single fit+rejection iteration of the pPXF fit for all input spectra with the provided set of constraints/options.

Parameters

  • templates (numpy.ndarray) – Full template library. Shape is (NTPL,NTPLPIX).

  • wave (numpy.ndarray) – Wavelength vector. Shape is (NPIX,).

  • flux (numpy.ndarray) – Object spectra to fit. Shape is (NSPEC,NPIX).

  • noise (numpy.ndarray) – Error in the object spectra to fit. Shape is (NSPEC,NPIX).

  • velscale (float) – The pixel scale of the object spectra in km/s.

  • start (list) – The starting kinematics for each kinematic component. Length is NCOMP.

  • moments (numpy.ndarray) – Integer vector with the number of kinematic moments for each component. Shape is (NCOMP,).

  • component (numpy.ndarray) – Integer vector identifying the kinematic component for each template. Shape is (NTPL,).

  • gas_template (numpy.ndarray) – Boolean vector that selects the gas templates. Shape is (NTPL,).

  • tpl_to_use (numpy.ndarray, optional) – Boolean vector selecting templates to consider during the fit. Shape is (NTPL,). If None, all templates are used in the fit.

  • reject_boxcar (int, optional) – Size of the window for the rejection statistics. Should be an odd number and larger and 10. Default is 101. If None, no rejection iteration is performed.

  • velscale_ratio (int, optional) – The ratio between the object and template pixel scale.

  • degree (int, optional) – Order of the additive polynomial to include in the fit. Not included by default.

  • mdegree (int, optional) – Order of the multiplicative polynomial to fit. Not included by default.

  • reddening (float, optional) – Initial E(B-V) guess for reddening (uses ppxf-default Calzetti 2000 model). No attentuation fit by default.

  • vgrp (array-like, optional) – The integer velocity group associated with each template. Shape is \((N_{\rm tpl},)\).

  • sgrp (array-like, optional) – The integer sigma group associated with each template. Shape is \((N_{\rm tpl},)\).

  • mask (numpy.ndarray, optional) – Boolean vector that selects the pixels in the object spectra to fit (i.e., mask=True for pixels to fit and mask=False for pixels to ignore). Shape is (NSPEC,NPIX). All pixels are fit by default.

  • vsyst (float, optional) – The pseudo velocity shift between the template and object spectra just due to the difference in the starting wavelength.

  • plot (bool, optional) – Show the pPXF fit plot at each iteration. Default is to skip the plot.

  • quiet (bool, optional) – Suppress output to the terminal (default).

  • sigma_rej (float, optional) – Sigma values used for the rejection. Default is 3.

Returns

Eleven arrays are returned:

  • (1) The best-fitting model for each spectrum [shape is (NSPEC,NPIX)];

  • (2) the best-fitting emission-line-only model for each spectrum [shape is (NSPEC,NPIX)];

  • (3) a boolean array that is True for all spectral pixels included in the fit [shape is (NSPEC,NPIX)];

  • (4) the best-fitting weight for each template in each spectrum [shape is (NSPEC,NTPL)];

  • (5) the error in the best-fitting template weights [shape is (NSPEC,NTPL)];

  • (6) the coefficients of the additive polynomial for each spectrum [shape is (NSPEC,DEGREE+1)]; -(7) the coefficients of the multiplicative polynomial for each spectrum [shape is (NSPEC,MDEGREE)];

  • (8) the best-fitting reddening values for each spectrum [shape is (NSPEC,)];

  • (9) the input kinematics for each fit [shape is (NSPEC,sum(MOMENTS)];

  • (10) the best-fit kinematics for each fit [shape is (NSPEC,sum(MOMENTS)];

  • (11) the formal error in the best-fit kinematics for each fit [shape is (NSPEC,sum(MOMENTS)].

Return type

tuple

mangadap.contrib.xjmc._good_templates(templates, gas_template, mask, start, velscale, velscale_ratio, vsyst)[source]

Determine which of the templates to use during the fit.

Good template are any stellar-continuum template and any gas template that is non-zero over the expected fitting range.

The details of this code should be pulled directly from ppxf for consistency.

Parameters

  • templates (numpy.ndarray) – Templates library to use for fitting. Shape is (NTPLPIX,NTPL).

  • gas_template (numpy.ndarray) – Boolean vector that selects the gas templates. Shape is (NTPL,).

  • mask (numpy.ndarray) – Boolean vector that selects the pixels in the object spectrum to fit (i.e., mask=True for pixels to fit and mask=False for pixels to ignore). As in pPXF, the length is expected to be less than or equal to NTPLPIX in the template spectra.

  • start (list) – The starting kinematics for each kinematic component. Length is NCOMP.

  • velscale (float) – The pixel scale of the object spectrum to fit in km/s.

  • velscale_ratio (int, optional) – The ratio between the object and template pixel scale.

  • vsyst (float, optional) – The pseudo velocity shift between the template and object spectra just due to the difference in the starting wavelength.

Returns

Boolean array flagging good templates, which means anything that is not a gas template and any gas template that has non-zero values in the fitting region.

Return type

numpy.ndarray

mangadap.contrib.xjmc._ppxf_component_setup(component, gas_template, start, single_gas_component=False, gas_start=None)[source]

Setup the component, moment, and starting point arrays for a ppxf-fitting interation.

This primarily just sets all the gas components to a single component if requested. It also restructures the moment and starting point arrays as necessary to reflect this change.

..warning:

This function requires that all stellar components have
component numbers that are **less than** any gas components.
However, this **is not checked** by the function.
Parameters

  • component (numpy.ndarray) – The full list of components for all templates. The total number of components is NCOMP.

  • gas_template (numpy.ndarray) – A boolean array identifying the gas templates.

  • start (list, numpy.ndarray) – The starting kinematics to use for each object spectrum. Shape is (NOBJ,); each element has shape (NCOMP,); each component element has shape (NMOM,), such that the number of moments can be different for each component. NCOMP and NMOM should be the same for all object spectra.

  • single_gas_component (bool, optional) – Flag to force all gas components to have the same kinematics.

  • gas_start (list, numpy.ndarray, optional) – The starting kinematics to use for the gas components. Shape must be (NOBJ,2).

Returns

  • (1) The list of downselected and renumbered, if necessary, kinematic components,

  • (2) the downselected and reordered, if necessary, number of moments to fit, and

  • (3) the downselected and reordered starting guesses for each component.

Return type

Three numpy arrays are returned

Raises

ValueError – Raised if the provided gas starting kinematics is not correct.

mangadap.contrib.xjmc._reorder_solution(ppsol, pperr, component_map, moments, start=None, fill_value=- 999.0)[source]

Provided the best-fitting parameters from a ppxf instance, restructure the parameters to account for components that were removed during the template validation.

Parameters

  • ppsol (list) – The pPXF solution parameters

  • pperr (list) – The formal errors on the pPXF solution parameters

  • component_map (numpy.ndarray) – An integer vector mapping the input component number to the output component number; i.e., component_map[0] is the original component number for the downselected 0th component; length is _NCOMP.

  • moments (list) – The number of moments for the original set of components; length is NCOMP.

  • start (list, optional) – The starting kinematics for the original set of components. If provided, the starting values are included in the output parameter object for components that were not included in the pPPXF fit; otherwise, the unfit components are given placeholder parameter values.

  • fill_value (float, optional) – The placeholder value to give parameters and errors for components not included in the pPXF fit.

Returns

Two lists with the rearranged best-fitting parameters and errors.

Return type

list

mangadap.contrib.xjmc._reset_components(c, valid)[source]
mangadap.contrib.xjmc._set_to_using_optimal_templates(nspec, ntpl, wgts, component, vgrp=None, sgrp=None)[source]
mangadap.contrib.xjmc._validate_templates_components(templates, gas_template, component, vgrp, sgrp, moments, mask, start, tpl_to_use, velscale, velscale_ratio=None, vsyst=0)[source]

Check that templates are valid in the sense that they have non-zero components in valid pixel regions.

If all templates are valid, the returned data is identical to the input. If not, the returned data are restructured as necessary for running pPXF.

The start vector is used to set the guess offset (including vsyst) between the provided mask and the template. The tpl_to_use vector is used to set a tempate as invalid.

Parameters

  • templates (numpy.ndarray) – Templates library to use for fitting. Shape is (NTPLPIX,NTPL).

  • gas_template (numpy.ndarray) – Boolean vector that selects the gas templates. Shape is (NTPL,).

  • component (numpy.ndarray) – Integer vector identifying the kinematic component for each template. Shape is (NTPL,).

  • vgrp (array-like) – The integer velocity group associated with each template. Shape is \((N_{\rm tpl},)\) , but can be None.

  • sgrp (array-like) – The integer sigma group associated with each template. Shape is \((N_{\rm tpl},)\) , but can be None.

  • moments (numpy.ndarray) – Integer vector with the number of kinematic moments for each component. Shape is (NCOMP,).

  • mask (numpy.ndarray) – Boolean vector that selects the pixels in the object spectrum to fit (i.e., mask=True for pixels to fit and mask=False for pixels to ignore). As in pPXF, the length is expected to be less than or equal to NTPLPIX in the template spectra.

  • start (list) – The starting kinematics for each kinematic component. Length is NCOMP.

  • tpl_to_use (numpy.ndarray) – In addition to removing unconstrained templates, this boolean vector selects that should even be considered in the fit. Shape is (NTPL,).

  • velscale (float) – The pixel scale of the object spectrum to fit in km/s.

  • velscale_ratio (int, optional) – The ratio between the object and template pixel scale.

  • vsyst (float, optional) – The pseudo velocity shift between the template and object spectra just due to the difference in the starting wavelength.

Returns

Ten arrays are returned:

  • (1) Boolean vector with which templates were valid (length is NTPL),

  • (2) the valid set of templates to pass to pPXF [shape is (NTPLPIX,_NTPL)],

  • (3) the boolean vector selecting gas templates (length is _NTPL),

  • (4) an integer vector mapping the input component number to the output component number (i.e., component_map[0] is the original component number for the downselected 0th component; length is _NCOMP),

  • (5) the new component number for the downselected templates (length is _NTPL),

  • (6) the new velocity group number for the downselected templates (length is _NTPL),

  • (7) the new sigma group number for the downselected templates (length is _NTPL),

  • (8) the number of moments for the new components (length is _NCOMP),

  • (9) the starting kinematics for each new component (length is _NCOMP), and

  • (10) the parameter tying object reordered as necessary for the new component list (this needs to be checked).

Return type

tuple

Raises

ValueError – Raised if no templates are valid.

mangadap.contrib.xjmc.calculate_noise(residuals, width=101)[source]

Robust determination of the error spectrum as 1/2 of the interval enclosing 68% of the values in a given running window. Created by Michele Cappellari (23 September 2017)

Parameters

  • residuals (numpy.ndarray) – Vector of residuals between the model and data

  • width (int) – (Optional) Size of the window for the statistics. Should be an odd number and larger and 10. Default is 101.

Returns

Vector with the same size as the input residuals with half of the 68% confidence interval of the residuals within a box of size width centered at each position.

Return type

numpy.ndarray

Raises

ValueError – Raised if the width is not an odd number or if it is less than 11 elements.

mangadap.contrib.xjmc.emline_fitter_with_ppxf(templates, wave, flux, noise, mask, velscale, velscale_ratio, inp_component, gas_template, inp_moments, inp_start, vgrp=None, sgrp=None, degree=- 1, mdegree=0, reddening=None, reject_boxcar=101, vsyst=0, tpl_to_use=None, binid=None, flux_binned=None, noise_binned=None, mask_binned=None, x_binned=None, y_binned=None, x=None, y=None, plot=False, quiet=False, debug=False, sigma_rej=3.0)[source]

Main calling function for fitting stellar-continuum and nebular emission lines in many spectra using pPXF.

This is a generalization of the original function provided by Xihan Ji and Michele Cappellari.

The function does not fit for the stellar kinematics; these are fixed during the fit (as provided in inp_start) and should have resulted from a previous fit to the stellar-continuum only; see mangadap.proc.ppxffit.PPXFFit. The number of stellar kinematic moments must have been the same for all spectra, and there can only be one stellar component.

The templates are expected to be an integer number of velscale_ratio in length; see mangadap.proc.ppxffit.PPXFFit.check_templates().

The fitting procedure can be performed for a single set of spectra, or a set of spectra that are remapped from an input set of binned spectra. The latter operation is selected by providing the binned flux, error, and mask arrays. The individual spectra can be mapped to a binned spectrum using binned and unbinned on-sky coordinates or by providing the bin indices directly (see argument description below).

When the binned spectra are provided, the fitting procedure is as follows:

  • The binned spectra are fit with the stellar components fixed to the provided kinematics in the starting value array and with all the gas templates part of a single kinematic component. This first fit iteration includes any rejection iteration according to the provided boxcar width.

  • The nearest binned spectrum is then found for each provided spectrum based on the provided coordinates. The fit to the binned spectrum is then used to set (1) the single optimal stellar template and (2) the initial guess for the gas kinematics to use for the subsequent fits to each individual spectrum

  • Each spectrum is fit for the first time with the stellar kinematics fixed to the result for the associated binned spectrum and, again, with all the gas templates free but part of the same kinematic component. This fit iteration includes any rejection iteration according to the provided boxcar width.

  • Finally the spectra are fit without any rejection iteration and allowing the gas templates to be associated with multiple kinematic components as requested by the user.

When no binned spectra are provided, the procedure is virtually the same except the initial fit to the binned spectra is skipped. An initial fit to the spectra is performed to construct the optimal template, instead of basing the optimal template on the initial fit to the binned spectrum.

To tie the kinematics assigned to each template, you have to assign them to velocity or velocity dispersion (sigma) groups using vgrp and sgrp, respectively. These arrays are used to construct the ppxf tied argument, appropriate for each spectrum fit.

Each template is identified as a gas template using the provided gas_template argument.

Todo

  • Allow mask(s) to be optional

  • Update the docs

  • Skip the last step if the gas are already part of the same kinematic component as dictated by the input tying data.

Parameters

  • templates (numpy.ndarray) – Templates library to use for fitting. Shape is (NTPLPIX,NTPL).

  • wave (numpy.ndarray) – Wavelength vector. Shape is (NPIX,).

  • flux (numpy.ndarray) – Object spectra to fit. Shape is (NSPEC,NPIX).

  • noise (numpy.ndarray) – Error in the object spectra to fit. Shape is (NSPEC,NPIX).

  • mask (numpy.ndarray) – Boolean vector that selects the pixels in the object spectra to fit (i.e., mask=True for pixels to fit and mask=False for pixels to ignore). Shape is (NSPEC,NPIX). All pixels are fit by default.

  • velscale (float) – The pixel scale of the object spectra in km/s.

  • velscale_ratio (int) – The ratio between the object and template pixel scale; must be an integer.

  • inp_component (numpy.ndarray) – Integer vector identifying the kinematic component for each template. Shape is (NTPL,).

  • gas_template (numpy.ndarray) – Boolean vector that selects the gas templates. Shape is (NTPL,).

  • inp_moments (numpy.ndarray) – Integer vector with the number of kinematic moments for each component. Shape is (NCOMP,).

  • inp_start (list, numpy.ndarray) – The starting kinematics to use for each spectrum. Shape is (NSPEC,); each element has shape (NCOMP,); each component element has shape (NMOM,), such that the number of moments can be different for each component. NCOMP and NMOM should be the same for all object spectra.

  • vgrp (array-like, optional) – The integer velocity group associated with each template. Shape is \((N_{\rm tpl},)\).

  • sgrp (array-like, optional) – The integer sigma group associated with each template. Shape is \((N_{\rm tpl},)\).

  • degree (int, optional) – Order of the additive polynomial to include in the fit. Not included by default.

  • mdegree (int, optional) – Order of the multiplicative polynomial to fit. Not included by default.

  • reddening (float, optional) – Initial E(B-V) guess for reddening (uses ppxf-default Calzetti 2000 model). No attentuation fit by default.

  • reject_boxcar (int, optional) – Size of the window for the rejection statistics. Should be an odd number and larger and 10. Default is 101. If None, no rejection iterations are performed.

  • vsyst (float, optional) – The pseudo velocity shift between the template and object spectra just due to the difference in the starting wavelength. Default is 0 km/s.

  • tpl_to_use (numpy.ndarray, optional) – Boolean vector selecting templates to consider during the fit. If None, all templates are used in the fit. If provided, the shape must be (NBIN,NTPL) when providing the binned data and (NSPEC,NTPL) when no binned data are provided.

  • binid (numpy.ndarray, optional) – Bin index associated with each spectrum. Ignored if binned spectra are not provided. If binned spectra are provided, and this is None, coordinates must be provided and they are used to associate each bin with a binned spectrum just based by proximity. If provided, this associates each spectrum to the binned spectrum to use for the stellar kinematics. Shape is (NSPEC,).

  • flux_binned (numpy.ndarray, optional) – Binned spectra with previous fits to the stellar kinematics. See purpose above.

  • noise_binned (numpy.ndarray, optional) – Error in the binned spectra.

  • mask_binned (numpy.ndarray, optional) – Mask for the binned spectra.

  • x_binned (numpy.ndarray, optional) – On-sky bin x coordinate; shape is (NBIN,).

  • y_binned (numpy.ndarray, optional) – On-sky bin y coordinate; shape is (NBIN,).

  • x (numpy.ndarray, optional) – On-sky spectrum x coordinates; shape is (NSPEC,)

  • y (numpy.ndarray, optional) – On-sky spectrum y coordinates; shape is (NSPEC,).

  • plot (bool, optional) – Show the pPXF fit plot at each iteration. Default is to skip the plot.

  • quiet (bool, optional) – Suppress output to the terminal (default).

  • debug (bool, optional) – Run in debugging mode. Currently, all this does is perform the initial setup and then return empty vectors of the correct shape. No fits are performed.

Returns

  • (1) The best-fitting model for each spectrum [shape is (NSPEC,NPIX)];

  • (2) the best-fitting emission-line-only model for each spectrum [shape is (NSPEC,NPIX)];

  • (3) a boolean array that is True for all spectral pixels included in the fit [shape is (NSPEC,NPIX)];

  • (4) the best-fitting weight for each template in each spectrum [shape is (NSPEC,NTPL)];

  • (5) the error in the best-fitting template weights [shape is (NSPEC,NTPL)];

  • (6) the coefficients of the additive polynomial for each spectrum [shape is (NSPEC,DEGREE+1)], None if not fit;

  • (7) the coefficients of the multiplicative polynomial for each spectrum [shape is (NSPEC,MDEGREE)];

  • (8) the best-fitting reddening values for each spectrum [shape is (NSPEC,)], None if not fit;

  • (9) the input kinematics for each fit [shape is (NSPEC,sum(MOMENTS)], None if not fit;

  • (10) the best-fit kinematics for each fit [shape is (NSPEC,sum(MOMENTS)];

  • (11) the formal error in the best-fit kinematics for each fit [shape is (NSPEC,sum(MOMENTS)].

Return type

Eleven arrays are returned

Raises

  • NotImplementedError – Raised if the number of stellar components is larger than 1.

  • ValueError – Raised if: (1) only some of the necessary bin-remapping data has not been provided (see function description); (2) the template flag object does not have the correct shape; (3) the wavelength and flux vectors do not match; (4) any of the spectra are fully masked (i.e., there’s nothing to fit); or (5) the input list of kinematics does not have the correct length.

mangadap.contrib.xjmc.ppxf_tied_parameters(component, vgrp, sgrp, moments)[source]

Construct the object used to tie kinematic parameters in pPXF.

Note

  • The components and kinematics groups can potentially have reduntant information. E.g., If all sigma groups also have tied velocities, they’ll be part of a component and will not required a tied parameter.

Warning

  • high-order moments are not currently tied, but this is straight-forward to add.

Parameters

  • component (array-like) – The kinematic component assigned to each template. Shape is \((N_{\rm tpl},)\).

  • vgrp (array-like) – The velocity group assigned to each template. Shape is \((N_{\rm tpl},)\). Can be None for no groups.

  • sgrp (array-like) – The velocity-dispersion (sigma) group assigned to each template. Shape is \((N_{\rm tpl},)\). Can be None for no groups.

  • moments (array-like) – The number of moments assigned to each component. Can be negative for fixed parameters. Shape is \((N_{\rm comp},)\).

Returns

The tied object to pass to ppxf. Will be None if both vgrp or sgrp are None or when the consolidation of the groups and components result in no tying being necessary.

Return type

list

Raises

ValueError – Raised if the components or the groups are not an uninterupted sequence from 0..N-1, if the moments are provided for each component, or the length of the vgrp or sgrp arrays do not match the input component array.