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