Spectrum API¶
- class soxs.spectra.Spectrum(ebins, flux, binscale='linear')[source]¶
- add_absorption_line(line_center, line_width, equiv_width, line_type='gaussian')[source]¶
Add an absorption line to this spectrum.
- Parameters:
line_center (float, (value, unit) tuple, or
Quantity
) – The line center position in units of keV, in the observer frame.line_width (one or more float, (value, unit) tuple, or
Quantity
) – The line width (FWHM) in units of keV, in the observer frame. Can also input the line width in units of velocity in the rest frame. For the Voigt profile, a list, tuple, or array of two values should be provided since there are two line widths, the Lorentzian and the Gaussian (in that order).equiv_width (float, (value, unit) tuple, or
Quantity
) – The equivalent width of the line, in units of milli-Angstromline_type (string, optional) – The line profile type. Default: “gaussian”
- add_emission_line(line_center, line_width, line_amp, line_type='gaussian')[source]¶
Add an emission line to this spectrum.
- Parameters:
line_center (float, (value, unit) tuple, or
Quantity
) – The line center position in units of keV, in the observer frame.line_width (one or more float, (value, unit) tuple, or
Quantity
) – The line width (FWHM) in units of keV, in the observer frame. Can also input the line width in units of velocity in the rest frame. For the Voigt profile, a list, tuple, or array of two values should be provided since there are two line widths, the Lorentzian and the Gaussian (in that order).line_amp (float, (value, unit) tuple, or
Quantity
) – The integrated line amplitude in the units of the fluxline_type (string, optional) – The line profile type. Default: “gaussian”
- apply_foreground_absorption(nH, model='wabs', redshift=0.0, abund_table='angr')[source]¶
Given a hydrogen column density, apply galactic foreground absorption to the spectrum.
- Parameters:
nH (float, (value, unit) tuple, or
Quantity
) – The hydrogen column in units of 10**22 atoms/cm**2model (string, optional) – The model for absorption to use. Options are “wabs” (Wisconsin, Morrison and McCammon; ApJ 270, 119) or “tbabs” (Tuebingen-Boulder, Wilms, J., Allen, A., & McCray, R. 2000, ApJ, 542, 914). Default: “wabs”.
redshift (float, optional) – The redshift of the absorbing material. Default: 0.0
abund_table (string) – The abundance table to be used for abundances in the absorption model. Default is set in the SOXS configuration file, the default for which is “angr”. Built-in options are: “angr” : from Anders E. & Grevesse N. (1989, Geochimica et Cosmochimica Acta 53, 197) “aspl” : from Asplund M., Grevesse N., Sauval A.J. & Scott P. (2009, ARAA, 47, 481) “feld” : from Feldman U. (1992, Physica Scripta, 46, 202) “wilm” : from Wilms, Allen & McCray (2000, ApJ 542, 914 except for elements not listed which are given zero abundance) “lodd” : from Lodders, K (2003, ApJ 591, 1220) “cl17.03” : the default abundance table in Cloudy 17.03
- classmethod from_constant(const_flux, emin, emax, nbins, binscale='linear')[source]¶
Create a spectrum from a constant model.
- Parameters:
const_flux (float) – The value of the constant flux in the units of the spectrum.
emin (float, (value, unit) tuple, or
Quantity
) – The minimum energy of the spectrum in keV.emax (float, (value, unit) tuple, or
Quantity
) – The maximum energy of the spectrum in keV.nbins (integer) – The number of bins in the spectrum.
binscale (string, optional) – The scale of the energy binning: “linear” or “log”. Default: “linear”
- classmethod from_file(filename)[source]¶
Read a spectrum from an ASCII ECSV, FITS, or HDF5 file, in the forms written by
write_ascii_file()
write_fits_file()
, andwrite_h5_file()
.- Parameters:
filename (string) – The path to the file containing the spectrum.
- classmethod from_powerlaw(photon_index, redshift, norm, emin, emax, nbins, binscale='linear')[source]¶
Create a spectrum from a power-law model. Form of the model is F(E) = norm*(e/1 keV)**-photon_index.
- Parameters:
photon_index (float) – The photon index of the source.
redshift (float) – The redshift of the source.
norm (float) – The normalization of the source in units of photons/s/cm**2/keV at 1 keV in the source frame.
emin (float, (value, unit) tuple, or
Quantity
) – The minimum energy of the spectrum in keV.emax (float, (value, unit) tuple, or
Quantity
) – The maximum energy of the spectrum in keV.nbins (integer) – The number of bins in the spectrum.
binscale (string, optional) – The scale of the energy binning: “linear” or “log”. Default: “linear”
- classmethod from_xspec_model(model_string, params, emin, emax, nbins, binscale='linear')[source]¶
Create a model spectrum using a model string and parameters as input to XSPEC.
- Parameters:
model_string (string) – The model to create the spectrum from. Use standard XSPEC model syntax. Example: “wabs*mekal”
params (list) – The list of parameters for the model. Must be in the order that XSPEC expects.
emin (float, (value, unit) tuple, or
Quantity
) – The minimum energy of the spectrum in keVemax (float, (value, unit) tuple, or
Quantity
) – The maximum energy of the spectrum in keVnbins (integer) – The number of bins in the spectrum.
binscale (string, optional) – The scale of the energy binning: “linear” or “log”. Default: “linear”
- classmethod from_xspec_script(infile, emin, emax, nbins, binscale='linear')[source]¶
Create a model spectrum using a script file as input to XSPEC.
- Parameters:
infile (string) – Path to the script file to use.
emin (float, (value, unit) tuple, or
Quantity
) – The minimum energy of the spectrum in keV.emax (float, (value, unit) tuple, or
Quantity
) – The maximum energy of the spectrum in keV.nbins (integer) – The number of bins in the spectrum.
binscale (string, optional) – The scale of the energy binning: “linear” or “log”. Default: “linear”
- generate_energies(t_exp, area, prng=None, quiet=False)[source]¶
Generate photon energies from this spectrum given an exposure time and effective area.
- Parameters:
t_exp (float, (value, unit) tuple, or
Quantity
) – The exposure time in seconds.area (float, (value, unit) tuple, or
Quantity
) – The effective area in cm**2. If one is creating events for a SIMPUT file, a constant should be used, and it must be large enough so that a sufficiently large sample is drawn for the ARF.prng (
RandomState
object, integer, or None) – A pseudo-random number generator. This will typically only be specified if you have a reason to generate the same set of random numbers, such as for a test. Default is None, which sets the seed based on the system time.quiet (boolean, optional) – If True, log messages will not be displayed when creating energies. Useful if you have to loop over a lot of spectra. Default: False
- get_flux_in_band(emin, emax)[source]¶
Determine the total flux within a band specified by an energy range.
- Parameters:
- Returns:
A tuple of values for the flux/intensity in the
band (the first value is in terms of the photon)
rate, the second value is in terms of the energy rate.
- get_lum_in_band(emin, emax, redshift=0.0, dist=None, cosmology=None)[source]¶
Determine the total luminosity in the source within a band specified by an energy range.
- Parameters:
emin (float, (value, unit) tuple, or
Quantity
) – The minimum energy in the band, in keV.emax (float, (value, unit) tuple, or
Quantity
) – The maximum energy in the band, in keV.redshift (float) – The redshift to the source, assuming it is cosmological.
dist (float, (value, unit) tuple, or
Quantity
) – The distance to the source, if it is not cosmological. If a unit is not specified, it is assumed to be in kpc.cosmology (
Cosmology
object) – An AstroPy cosmology object used to determine the luminosity distance if needed. If not set, the default is the Planck 2018 cosmology.
- Returns:
A tuple of values for the luminosity in the band (the first)
value is in terms of the photon rate, the second value is
in terms of the energy rate.
- new_spec_from_band(emin, emax)[source]¶
Create a new
Spectrum
object from a subset of an existing one defined by a particular energy band.
- plot(lw=2, xmin=None, xmax=None, ymin=None, ymax=None, xscale=None, yscale=None, label=None, fontsize=18, fig=None, ax=None, **kwargs)[source]¶
Make a quick Matplotlib plot of the spectrum. A Matplotlib figure and axis is returned.
- Parameters:
lw (float, optional) – The width of the lines in the plots. Default: 2.0 px.
xmin (float, optional) – The left-most energy in keV to plot. Default is the minimum value in the spectrum.
xmax (float, optional) – The right-most energy in keV to plot. Default is the maximum value in the spectrum.
ymin (float, optional) – The lower extent of the y-axis. By default, it is set automatically.
ymax (float, optional) – The upper extent of the y-axis. By default, it is set automatically.
xscale (string, optional) – The scaling of the x-axis of the plot. Default: “log”
yscale (string, optional) – The scaling of the y-axis of the plot. Default: “log”
label (string, optional) – The label of the spectrum. Default: None
fontsize (int) – Font size for labels and axes. Default: 18
fig (
Figure
, optional) – A Figure instance to plot in. Default: None, one will be created if not provided.ax (
Axes
, optional) – An Axes instance to plot in. Default: None, one will be created if not provided.
- Return type:
- regrid_spectrum(emin, emax, nbins, binscale='linear')[source]¶
Regrid an existing spectrum to a new energy binning and return a new spectrum.
- Parameters:
emin (float, (value, unit) tuple, or
Quantity
) – The minimum energy in the band, in keV.emax (float, (value, unit) tuple, or
Quantity
) – The maximum energy in the band, in keV.nbins (integer) – The number of bins in the spectrum.
binscale (string, optional) – The scale of the energy binning: “linear” or “log”. Default: “linear”
- rescale_flux(new_flux, emin=None, emax=None, flux_type='photons')[source]¶
Rescale the flux of the spectrum, optionally using a specific energy band.
- Parameters:
new_flux (float) – The new flux in units of photons/s/cm**2.
emin (float, (value, unit) tuple, or
Quantity
, optional) – The minimum energy of the band to consider, in keV. Default: Use the minimum energy of the entire spectrum.emax (float, (value, unit) tuple, or
Quantity
, optional) – The maximum energy of the band to consider, in keV. Default: Use the maximum energy of the entire spectrum.flux_type (string, optional) –
- The units of the flux to use in the rescaling:
”photons”: photons/s/cm**2 “energy”: erg/s/cm**2
- write_ascii_file(specfile, overwrite=False)[source]¶
Write the spectrum to an ASCII file in the ECSV format (https://docs.astropy.org/en/stable/io/ascii/ecsv.html).
- Parameters:
specfile (string) – The filename to write the file to.
overwrite (boolean, optional) – Whether or not to overwrite an existing file with the same name. Default: False
- write_file(specfile, overwrite=False)[source]¶
Write a
Spectrum
object to disk, in any of three formats, which will be determined by the chosen suffix: ASCII ECSV: .dat, .txt. or .ecsv HDF5: .hdf5 or .h5 FITS: .fits- Parameters:
specfile (string) – The name of the file to write to.
overwrite (boolean, optional) – Whether or to overwrite an existing file with the same name. Default: False
- class soxs.spectra.CountRateSpectrum(ebins, flux, binscale='linear')[source]¶
- generate_energies(t_exp, prng=None, quiet=False)[source]¶
Generate photon energies from this count rate spectrum given an exposure time.
- Parameters:
t_exp (float, (value, unit) tuple, or
Quantity
) – The exposure time in seconds.prng (
RandomState
object, integer, or None) – A pseudo-random number generator. Typically will only be specified if you have a reason to generate the same set of random numbers, such as for a test. Default is None, which sets the seed based on the system time.quiet (boolean, optional) – If True, log messages will not be displayed when creating energies. Useful if you have to loop over a lot of spectra. Default: False
- new_spec_from_band(emin, emax)¶
Create a new
Spectrum
object from a subset of an existing one defined by a particular energy band.
- rescale_flux(new_flux, emin=None, emax=None, flux_type='photons')¶
Rescale the flux of the spectrum, optionally using a specific energy band.
- Parameters:
new_flux (float) – The new flux in units of photons/s/cm**2.
emin (float, (value, unit) tuple, or
Quantity
, optional) – The minimum energy of the band to consider, in keV. Default: Use the minimum energy of the entire spectrum.emax (float, (value, unit) tuple, or
Quantity
, optional) – The maximum energy of the band to consider, in keV. Default: Use the maximum energy of the entire spectrum.flux_type (string, optional) –
- The units of the flux to use in the rescaling:
”photons”: photons/s/cm**2 “energy”: erg/s/cm**2
- class soxs.spectra.ConvolvedSpectrum(ebins, flux, arf, binscale='linear')[source]¶
- deconvolve()[source]¶
Return the deconvolved
Spectrum
object associated with this convolved spectrum.
- generate_energies(t_exp, prng=None, quiet=False)[source]¶
Generate photon energies from this convolved spectrum given an exposure time.
- Parameters:
t_exp (float, (value, unit) tuple, or
Quantity
) – The exposure time in seconds.prng (
RandomState
object, integer, or None) – A pseudo-random number generator. Typically will only be specified if you have a reason to generate the same set of random numbers, such as for a test. Default is None, which sets the seed based on the system time.quiet (boolean, optional) – If True, log messages will not be displayed when creating energies. Useful if you have to loop over a lot of spectra. Default: False
- new_spec_from_band(emin, emax)[source]¶
Create a new
ConvolvedSpectrum
object from a subset of an existing one defined by a particular energy band.
- rescale_flux(new_flux, emin=None, emax=None, flux_type='photons')¶
Rescale the flux of the spectrum, optionally using a specific energy band.
- Parameters:
new_flux (float) – The new flux in units of photons/s/cm**2.
emin (float, (value, unit) tuple, or
Quantity
, optional) – The minimum energy of the band to consider, in keV. Default: Use the minimum energy of the entire spectrum.emax (float, (value, unit) tuple, or
Quantity
, optional) – The maximum energy of the band to consider, in keV. Default: Use the maximum energy of the entire spectrum.flux_type (string, optional) –
- The units of the flux to use in the rescaling:
”photons”: photons/s/cm**2 “energy”: erg/s/cm**2