The SpecAnalysis Module
The SpecAnalysis module provides a range of functions for spectral analsysis in the context of the Sculptor packages SpecOneD, SpecFit, and SpecModel classes.
- sculptor.specanalysis.analyze_continuum(specfit, model_names, rest_frame_wavelengths, cosmology, redshift=None, dispersion=None, cont_meas=None, width=10)
Calculate measurements of the continuum at a range of specified wavelengths for a spectral fit (SpecFit object).
At present this analysis assumes that the spectra are in the following units: flux density - erg/s/cm^2/AA dispersion - AA
- Parameters:
specfit (sculptor.specfit.SpecFit) – SpecFit class object to extract the model flux from
model_names (list(string)) – List of model names to create the emission feature flux from.
rest_frame_wavelengths (list(float)) – Rest-frame wavelength of the emission feature
cosmology (astropy.cosmology.Cosmology) – Cosmology for calculation of absolute properties
redshift (float) – Redshift of the object. This keyword argument defaults to ‘None’, in which case the redshift from the SpecFit object is used.
dispersion (np.array) – This keyword argument allows to input a dispersion axis (e.g., wavelengths) for which the model fluxes are calculated. The value defaults to ‘None’, in which case the dispersion from the SpecFit spectrum is being used.
cont_meas (list(string)) – This keyword argument allows to specify the list of emission feature measurements. Currently possible measurements are [‘peak_fluxden’, ‘peak_redsh’, ‘EW’, ‘FWHM’, ‘flux’]. The value defaults to ‘None’ in which all measurements are calculated
width ([float, float]) – Window width in dispersion units to calculate the average flux density in.
- Returns:
Dictionary with measurement results (with units)
- Return type:
dict
- sculptor.specanalysis.analyze_emission_feature(specfit, feature_name, model_names, rest_frame_wavelength, cont_model_names=None, redshift=None, dispersion=None, emfeat_meas=None, disp_range=None, cosmology=None, fwhm_method='spline')
Calculate measurements of an emission feature for a spectral fit ( SpecFit object).
At present this analysis assumes that the spectra are in the following units: flux density - erg/s/cm^2/AA dispersion - AA
- Parameters:
specfit (sculptor.specfit.SpecFit) – SpecFit class object to extract the model flux from
feature_name (string) – Name of the emission feature, which will be used to name the resulting measurements in the output dictionary.
model_names (list) – List of model names to create the emission feature flux from.
rest_frame_wavelength (float) – Rest-frame wavelength of the emission feature
cont_model_names (list) – List of model names to create the continuum flux model from. The continuum spectrum is for example used in the calculation of some emission feature properties (e.g. equivalent width).
redshift (float) – Redshift of the object. This keyword argument defaults to ‘None’, in which case the redshift from the SpecFit object is used.
dispersion (np.array) – This keyword argument allows to input a dispersion axis (e.g., wavelengths) for which the model fluxes are calculated. The value defaults to ‘None’, in which case the dispersion from the SpecFit spectrum is being used.
emfeat_meas (list) – This keyword argument allows to specify the list of emission feature measurements. Currently possible measurements are [‘peak_fluxden’, ‘peak_redsh’, ‘EW’, ‘FWHM’, ‘flux’]. The value defaults to ‘None’ in which all measurements are calculated
disp_range (list) – 2 element list holding the lower and upper dispersion boundaries for the integration
cosmology (astropy.cosmology class) – Cosmology for calculating luminosities
fwhm_method (string) – Method to use for calculating the FWHM. Possible values are ‘sign’ or ‘spline’ (default).
- Returns:
Dictionary with measurement results (with units)
- Return type:
dict
- sculptor.specanalysis.analyze_mcmc_results(foldername, specfit, continuum_dict, emission_feature_dictlist, redshift, cosmology, emfeat_meas=None, cont_meas=None, dispersion=None, width=10, concatenate=False)
Analyze MCMC model fit results of specified continuum/feature models.
Results will be written to an enhanced csv file in the same folder, where the MCMC flat chain data resides.
Important: Only model functions that are sampled together can be analyzed together. This means that only model functions from ONE SpecModel can also be analyzed together. Additionally, only model functions for which all variable parameters have sampled by the MCMC fit are analyzed.
The following parameters should be specified in the continuum_listdict:
‘model_names’ - list of model function prefixes for the full continuum model
‘rest_frame_wavelengths’ - list of rest-frame wavelengths (float) for which fluxes, luminosities and magnitudes should be calculated
The other arguments for the SpecAnalysis.analyze_continuum are provided to the MCMC analysis function separately.
The following parameters should be specified in the emission_feature_listdict:
‘feature_name’ - name of the emission feature, which will be used to name the resulting measurements in the output file.
‘model_names’ - list of model names to create the emission feature model flux from.
‘rest_frame_wavelength’ - rest-frame wavelength of the emission feature.
Additionally, one can specify:
‘disp_range’ - 2 element list holding the lower and upper dispersion boundaries flux density integration.
- Parameters:
foldername (string) – Path to the folder with the MCMC flat chain hdf5 files.
specfit (sculptor.specfit.SpecFit) – Sculptor model fit (SpecFit object) containing the information about the science spectrum, the SpecModels and parameters.
continuum_dict (dictionary) – The continuum_listdict holds the arguments for the SpecAnalysis.analyze_continuum function that will be called by this procedure.
emission_feature_dictlist (list of dictionary) – The emission_feature_listdict hold the arguments for the SpecAnalysis.analyze_emission_feature functions that will be called by this procedure.
redshift (float) – Source redshift
cosmology (astropy.cosmology.Cosmology) – Cosmology for calculation of absolute properties
emfeat_meas (list(string)) – This keyword argument allows to specify the list of emission feature measurements. Currently possible measurements are [‘peak_fluxden’, ‘peak_redsh’, ‘EW’, ‘FWHM’, ‘flux’]. The value defaults to ‘None’ in which all measurements are calculated
cont_meas (list(string)) – This keyword argument allows to specify the list of emission feature measurements. Currently possible measurements are [‘peak_fluxden’, ‘peak_redsh’, ‘EW’, ‘FWHM’, ‘flux’]. The value defaults to ‘None’ in which all measurements are calculated
dispersion (np.array) – This keyword argument allows to input a dispersion axis (e.g., wavelengths) for which the model fluxes are calculated. The value defaults to ‘None’, in which case the dispersion from the SpecFit spectrum is being used.
width ([float, float]) – Window width in dispersion units to calculate the average flux density in.
concatenate (bool) – Boolean to indicate whether the MCMC flat chain and the analysis results should be concatenated before written to file. (False = Only writes analysis results to file; True = Writes analysis results and MCMC flat chain parameter values to file)
- Returns:
None
- sculptor.specanalysis.analyze_resampled_results(specfit, foldername, resampled_df_name, continuum_dict, emission_feature_dictlist, redshift, cosmology, emfeat_meas=None, cont_meas=None, dispersion=None, width=10, concatenate=False)
Analyze resampled model fit results for all specified continuum and feature models.
Results will be written to an enhanced csv file in the same folder, where the resampled raw data resides.
The following parameters should be specified in the continuum_listdict:
‘model_names’ - list of model function prefixes for the full continuum model
‘rest_frame_wavelengths’ - list of rest-frame wavelengths (float) for which fluxes, luminosities and magnitudes should be calculated
The other arguments for the SpecAnalysis.analyze_continuum are provided to the MCMC analysis function separately.
The following parameters should be specified in the emission_feature_listdict:
‘feature_name’ - name of the emission feature, which will be used to name the resulting measurements in the output file.
‘model_names’ - list of model names to create the emission feature model flux from.
‘rest_frame_wavelength’ - rest-frame wavelength of the emission feature.
Additionally, one can specify:
‘disp_range’ - 2 element list holding the lower and upper dispersion boundaries flux density integration.
- Parameters:
specfit (sculptor.specfit.SpecFit) – Sculptor model fit (SpecFit object) containing the information about the science spectrum, the SpecModels and parameters.
foldername (string) – Path to the folder with the resampled raw hdf5 file.
resampled_df_name (str) – Filename of the resampled raw DataFrame saved in hdf5 format.
continuum_dict (dictionary) – The continuum_listdict holds the arguments for the SpecAnalysis.analyze_continuum function that will be called by this procedure.
emission_feature_dictlist (list of dictionary) – The emission_feature_listdict hold the arguments for the SpecAnalysis.analyze_emission_feature functions that will be called by this procedure.
redshift (float) – Source redshift
cosmology (astropy.cosmology.Cosmology) – Cosmology for calculation of absolute properties
emfeat_meas (list(string)) – This keyword argument allows to specify the list of emission feature measurements. Currently possible measurements are [‘peak_fluxden’, ‘peak_redsh’, ‘EW’, ‘FWHM’, ‘flux’]. The value defaults to ‘None’ in which all measurements are calculated
cont_meas (list(string)) – This keyword argument allows to specify the list of emission feature measurements. Currently possible measurements are [‘peak_fluxden’, ‘peak_redsh’, ‘EW’, ‘FWHM’, ‘flux’]. The value defaults to ‘None’ in which all measurements are calculated
dispersion (np.array) – This keyword argument allows to input a dispersion axis (e.g., wavelengths) for which the model fluxes are calculated. The value defaults to ‘None’, in which case the dispersion from the SpecFit spectrum is being used.
width ([float, float]) – Window width in dispersion units to calculate the average flux density in.
concatenate (bool) – Boolean to indicate whether the MCMC flat chain and the analysis results should be concatenated before written to file. (False = Only writes analysis results to file; True = Writes analysis results and MCMC flat chain parameter values to file)
- Returns:
None
- sculptor.specanalysis.build_model_flux(specfit, model_list, dispersion=None)
Build the model flux from a specified list of models that exist in the SpecModels of the SpecFit object.
The dispersion axis for the model flux can be specified as a keyword argument.
- Parameters:
specfit (sculptor.specfit.SpecFit) – SpecFit class object to extract the model flux from
model_list (list(string)) – List of model names to create the model flux from. The models must be exist in the SpecModel objects inside the SpecFit object.
dispersion (np.array) – New dispersion to create the model flux for
- Returns:
SpecOneD objects with the model flux
- Return type:
sod.SpecOneD
- sculptor.specanalysis.calc_absolute_mag_from_apparent_mag(appmag, cosmology, redshift, kcorrection=True, a_nu=0)
Calculate the absolute magnitude from the apparent magnitude using a power law k-correction.
- Parameters:
appmag (float) – Apparent AB magnitude
cosmology (astropy.cosmology.Cosmology) – Cosmology as an astropy Cosmology object.
redshift (float) – Redshift of the source.
kcorrection (bool) – Boolean to indicate whether the magnitude should be k-corrected assuming a power law spectrum. This keyword argument defaults to ‘True’.
a_nu (float) – Power law slope as a function of frequency for the k-correction. This defaults to ‘0’, appropriate for monochromatic measurements.
- Returns:
Absolute AB magnitude (monochromatic)
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.calc_absolute_mag_from_fluxden(fluxden, dispersion, cosmology, redshift, kcorrection=True, a_nu=0)
Calculate the absolute AB magnitude from the monochromatic flux density at a given dispersion value.
- Parameters:
fluxden (astropy.units.Quantity) – Monochromatic flux density at a given wavelength.
dispersion (float) – Dispersion value (usually in wavelength).
cosmology (astropy.cosmology.Cosmology) – Cosmology as an astropy Cosmology object.
redshift (float) – Redshift of the source.
kcorrection (bool) – Boolean to indicate whether the magnitude should be k-corrected assuming a power law spectrum. This keyword argument defaults to ‘True’.
a_nu (float) – Power law slope as a function of frequency for the k-correction. This defaults to ‘0’, appropriate for monochromatic measurements.
- Returns:
Absolute AB magnitude (monochromatic)
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.calc_absolute_mag_from_monochromatic_luminosity(l_wav, wavelength)
Calculate the absolute monochromatic magnitude from the monochromatic luminosity per wavelegnth.
- Parameters:
l_wav (astropy.units.Quantity) – Monochromatic luminosity per wavelength
wavelength (float) – Wavelength of the monochromatic luminosity
- Returns:
Absolute monochromatic magnitude
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.calc_apparent_mag_from_fluxden(fluxden, dispersion)
Calculate the apparent AB magnitude from the monochromatic flux density at a specified dispersion value.
- Parameters:
fluxden (astropy.units.Quantity) – Monochromatic flux density at a given wavelength.
dispersion (float) – Dispersion value (usually in wavelength).
- Returns:
Returns apparent AB magnitude.
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.calc_integrated_luminosity(input_spec, redshift, cosmology, disp_range=None)
Calculate the integrated model spectrum luminosity.
- Parameters:
input_spec (sculptor.speconed.SpecOneD) – Input spectrum
redshift (float) – Redshift of the source.
cosmology (astropy.cosmology.Cosmology) – Cosmology as an astropy Cosmology object
disp_range ([float, float]) – 2 element list holding the lower and upper dispersion boundaries for the integration
- Returns:
Return the integrated luminosity for (dispersion range in) the input spectrum.
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.calc_lwav_from_fwav(fluxden, redshift, cosmology)
Calculate the monochromatic luminosity from the monochromatic flux density.
- Parameters:
fluxden (astropy.units.Unit or astropy.units.Quantity or astropy.units.CompositeUnit or astropy.units.IrreducibleUnit) – Monochromatic flux density at a given wavelength.
redshift (float) – Redshift of the source.
cosmology (astropy.cosmology.Cosmology) – Cosmology as an astropy Cosmology object
- Returns:
Monochromatic luminosity in units of erg s^-1 Angstroem^-1
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.get_average_fluxden(input_spec, dispersion, width=10, redshift=0)
Calculate the average flux density of a spectrum in a window centered at the specified dispersion and with a given width.
The central dispersion and width can be specified in the rest-frame and then are redshifted to the observed frame using the redsh keyword argument.
Warning: this function currently only works for spectra in wavelength units. For spectra in frequency units the conversion to rest-frame will be incorrect.
- Parameters:
input_spec (sculptor.speconed.SpecOneD) – Input spectrum
dispersion (float) – Central dispersion
width (float) – Width of the dispersion window
redshift (float) – Redshift argument to redshift the dispersion window into the observed frame.
- Returns:
Average flux density
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.get_equivalent_width(cont_spec, line_spec, disp_range=None, redshift=0)
Calculate the rest-frame equivalent width of a spectral feature.
Warning: this function currently only works for spectra in wavelength units. For spectra in frequency units the conversion to rest-frame will be incorrect.
- Parameters:
cont_spec (sculptor.speconed.SpecOneD) – Continuum spectrum
line_spec (sculptor.speconed.SpecOneD) – Spectrum with the feature (e.g. emission line)
disp_range ([float, float]) – Dispersion range (2 element list of floats) over which the equivalent width will be calculated.
redshift – Redshift of the astronomical source
- Returns:
Rest-frame equivalent width
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.get_fwhm(input_spec, disp_range=None, resolution=None, method='spline')
Calculate the FWHM (in km/s) of an emission feature from the spectrum.
The user can specify a dispersion range to limit the FWHM calculation to this part of the spectrum. If a resolution (R) is specified the FWHM is corrected for the broadening due to the resolution.
The function will subtract a flux density value of half of the maximum and then find the two roots (flux density = 0) of the new flux density axis. If the emission feature has multiple components more than two roots can be found in which case the a np.NaN value will be returned.
- Parameters:
input_spec (sculptor.speconed.SpecOneD) – Input spectrum
disp_range ([float, float]) – Dispersion range to which the calculation is limited.
resolution (float) – Resolution in R = Lambda/Delta Lambda
method (string) – Method to use in retrieving the FWHM. There are two methods available. The default method ‘spline’ uses a spline to interpolate the original spectrum and find the zero points using a root finding algorithm on the spline. The second method ‘sign’ finds sign changes in the half peak flux subtracted spectrum.
- Returns:
FWHM of the spectral feature
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.get_integrated_flux(input_spec, disp_range=None)
Calculate the integrated flux of a spectrum.
The keyword argument disp_range allows to specify the dispersion boundaries for the integration. The standard numpy.trapz function is used for the integration.
- Parameters:
input_spec (sculptor.speconed.SpecOneD) – SpecOneD object holding the spectrum to integrate
disp_range ([float, float]) – 2 element list holding the lower and upper dispersion boundaries for the integration
- Returns:
Integrated flux
- Return type:
astropy.units.Quantity
- sculptor.specanalysis.get_nonparametric_measurements(input_spec, line_rest_wavel, redshift, disp_range=None)
Measure the velocities at different ratios of the total emission line flux.
These velocity measurements are referenced in the literature by (e.g.) Whittle+1985, Liu+2013, Zakamska & Greene 2014.
This function calculates the cumulative integral of the emission line flux and then determines the closest dispersion values in velocity space to the 5%, 10%, 50%, 90% and 95% total flux ratios.
- Parameters:
input_spec (sculptor.speconed.SpecOneD) – Input spectrum
line_rest_wavel (float) – rest-frame wavelength fo the line in Angstroem
redshift (float) – Redshift of the source
disp_range ([float, float]) – Observed-frame dispersion range to which the calculation is limited.
- Returns:
median velocity, 5% velocity, 10% velocity, 90% velocity, 95% velocity, velocity resolution at median velocity, frequency of median velocity, wavelength of median velocity, redshift of median velocity
- Return type:
astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity, astropy.units.Quantity
- sculptor.specanalysis.get_peak_redshift(input_spec, rest_wave)
Calculate the redshift of the flux density peak in the spectrum by specifying the expected rest frame wavelength of the emission feature.
- Parameters:
input_spec (sculptor.speconed.SpecOneD) – Input spectrum
rest_wave – Rest-frame wavelength of the expected emission feature.
- Returns:
Redshift of the peak flux density
- Return type:
float
- sculptor.specanalysis.k_correction_pl(redshift, a_nu)
Calculate the k-correction for a power law spectrum with spectral index (per frequency) a_nu.
- Parameters:
redshift (float) – Cosmological redshift of the source
a_nu (float) – Power law index (per frequency)
- Returns:
K-correction
- Return type:
float