Spectrum API

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

classmethod from_count_rate_spectrum(spec, redshift=0.0, dist=None, cosmology=None)

Create a Spectrum from a CountRateSpectrum object, assuming that the latter is in the rest frame of the source. To get the Spectrum in the observer frame, you must either provide a redshift or a distance to the source to convert to flux. Note that the energy bins of the original CountRateSpectrum object will be cosmologically redshifted if the redshift is nonzero.

Parameters:

• spec (CountRateSpectrum) – The CountRateSpectrum object to create the Spectrum from.

• 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.

classmethod from_pyxspec_model(model, spectrum_index=None)

Create a spectrum from a PyXspec model object.

Parameters:

• model (Model) – The PyXspec model object.

• spectrum_index (integer, optional) – The index of the spectrum in the model object to use for getting the energies and fluxes. Default: Will use the first valid value of the spectral index, starting from zero.

classmethod from_spex_model(spex_session, isect=1)

Create a spectrum from a SPEX session.

Parameters:

• spex_session (Session) – The SPEX session object.

• isect (integer, optional) – The sector in the SPEX session to use. Default: 1.

classmethod from_xspec_model(model_string, params, emin, emax, nbins, binscale='linear', xspec_settings=None)

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”

• xspec_settings (dict, optional) – A dictionary of XSPEC settings to set before running the model, each of which will be run as (e.g.) “xset {key} {value}”. Default: None.

classmethod from_xspec_script(infile, emin, emax, nbins, binscale='linear', xspec_settings=None)

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”

• xspec_settings (dict, optional) – A dictionary of XSPEC settings to set before running the model, each of which will be run as (e.g.) “xset {key} {value}”. Default: None.

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 photon count rate and luminosity within a band specified by an energy range. Either a redshift or or an explicit distance must be specified in order to convert from the observer frame to the source frame.

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.

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.base.CountRateSpectrum(ebins, spec, binscale='linear')

classmethod from_constant(const_value, emin, emax, nbins, binscale='linear')

Create a spectrum from a constant model.

Parameters:

• const_value (float) – The value of the constant 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_powerlaw(photon_index, norm, emin, emax, nbins, binscale='linear')

Create a count rate spectrum from a power-law model, in the frame of the source. The form of the model is R(E) = norm*(e/(1 keV))**-photon_index.

Parameters:

• photon_index (float) – The photon index of the source.

• norm (float) – The normalization of the source in units of the spectrum, photons/s/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_spectrum(spec, redshift=0.0, dist=None, cosmology=None)

Create a CountRateSpectrum from a Spectrum object, assuming that the latter is in the observer frame. To get the CountRateSpectrum in the source frame, you must either provide a redshift or a distance to the source to convert to photon count rate and luminosity. Note that the energy bins of the original Spectrum object will be cosmologically blueshifted if the redshift is nonzero.

Parameters:

• spec (Spectrum) – The Spectrum object to create the CountRateSpectrum from.

• 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.

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

get_lum_in_band(emin, emax)

Determine the total photon count rate and luminosity 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 rate/luminosity in the

• band (the first value is in terms of the photon)

• rate, the second value is in terms of the energy rate

• (or simply the luminosity).

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.

class soxs.spectra.base.ConvolvedSpectrum(ebins, flux, arf, rmf=None, binscale='linear', noisy=False, exp_time=None)

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.