Spectrum API

class soxs.spectra.Spectrum(ebins, flux, binscale='linear')

add_absorption_line(line_center, line_width, equiv_width, line_type='gaussian')

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-Angstrom

• line_type (string, optional) – The line profile type. Default: “gaussian”

add_emission_line(line_center, line_width, line_amp, line_type='gaussian')

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 flux

• line_type (string, optional) – The line profile type. Default: “gaussian”

apply_foreground_absorption(nH, model='wabs', redshift=0.0, abund_table='angr')

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**2

• model (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')

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)

Read a spectrum from an ASCII ECSV, FITS, or HDF5 file, in the forms written by write_ascii_file() write_fits_file(), and write_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')

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')

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 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_script(infile, emin, emax, nbins, binscale='linear')

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)

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)

Determine the total flux 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.

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)

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)

Create a new Spectrum object from a subset of an existing one defined by a particular energy band.

Parameters:

• emin (float, (value, unit) tuple, or Quantity) – The minimum energy of the band in keV.

• emax (float, (value, unit) tuple, or Quantity) – The maximum energy of the band in keV.

plot(lw=2, xmin=None, xmax=None, ymin=None, ymax=None, xscale=None, yscale=None, label=None, fontsize=18, fig=None, ax=None, **kwargs)

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:

A tuple of the Figure and the Axes objects.

regrid_spectrum(emin, emax, nbins, binscale='linear')

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')

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)

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)

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

write_fits_file(specfile, overwrite=False)

Write the spectrum to a FITS file.

Parameters:

• specfile (string) – The filename to write the file to.

• overwrite (boolean, optional) – Whether to overwrite an existing file with the same name. Default: False

write_hdf5_file(specfile, overwrite=False)

Write the spectrum to an HDF5 file.

Parameters:

• specfile (string) – The filename to write the file to.

• overwrite (boolean, optional) – Whether to overwrite an existing file with the same name. Default: False

class soxs.spectra.CountRateSpectrum(ebins, flux, binscale='linear')

generate_energies(t_exp, prng=None, quiet=False)

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.

Parameters:

• emin (float, (value, unit) tuple, or Quantity) – The minimum energy of the band in keV.

• emax (float, (value, unit) tuple, or Quantity) – The maximum energy of the band in keV.

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')

deconvolve()

Return the deconvolved Spectrum object associated with this convolved spectrum.

generate_energies(t_exp, prng=None, quiet=False)

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)

Create a new ConvolvedSpectrum object from a subset of an existing one defined by a particular energy band.

Parameters:

• emin (float, (value, unit) tuple, or Quantity) – The minimum energy of the band in keV.

• emax (float, (value, unit) tuple, or Quantity) – The maximum energy of the band in keV.

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