# Spectrum API¶

class soxs.spectra.Spectrum(ebins, flux)[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-Angstrom line_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 flux line_type (string, optional) – The line profile type. Default: “gaussian”
apply_foreground_absorption(nH, model='wabs', redshift=0.0)[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**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
classmethod from_constant(const_flux, emin, emax, nbins)[source]

Create a spectrum from a constant model using XSPEC.

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.
classmethod from_file(filename)[source]

Read a spectrum from an ASCII or HDF5 file.

If ASCII: accepts a file with two columns, the first being the center energy of the bin in keV and the second being the spectrum in the appropriate units, assuming a linear binning with constant bin widths.

If HDF5: accepts a file with one array dataset, named “spectrum”, which is the spectrum in the appropriate units, and two scalar datasets, “emin” and “emax”, which are the minimum and maximum energies in keV.

Parameters: filename (string) – The path to the file containing the spectrum.
classmethod from_powerlaw(photon_index, redshift, norm, emin, emax, nbins)[source]

Create a spectrum from a power-law model.

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.
classmethod from_xspec_model(model_string, params, emin, emax, nbins)[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 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.
classmethod from_xspec_script(infile, emin, emax, nbins)[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.
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. 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_flux_in_band(emin, emax)[source]

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

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)[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. A tuple of the Figure and the Axes objects.
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_file(specfile, overwrite=False)[source]

Write the spectrum to a file.

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_h5_file(specfile, overwrite=False)[source]

Write the spectrum to an HDF5 file.

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
class soxs.spectra.ApecGenerator(emin, emax, nbins, var_elem=None, apec_root=None, apec_vers=None, broadening=True, nolines=False, abund_table=None, nei=False)[source]

Initialize a thermal gas emission model from the AtomDB APEC tables available at http://www.atomdb.org. This code borrows heavily from Python routines used to read the APEC tables developed by Adam Foster at the CfA (afoster@cfa.harvard.edu).

Parameters: emin (float, (value, unit) tuple, or Quantity) – The minimum energy for the spectral model. emax (float, (value, unit) tuple, or Quantity) – The maximum energy for the spectral model. nbins (integer) – The number of bins in the spectral model. var_elem (list of strings, optional) – The names of elements to allow to vary freely from the single abundance parameter. These can be strings like [“O”, “N”, “He”], or if nei=True they must be elements with ionization states, e.g. [“O^1”, “O^2”, “N^4”]. Default: None apec_root (string, optional) – The directory root where the APEC model files are stored. If not provided, the default is to grab them from the tables stored with SOXS. apec_vers (string, optional) – The version identifier string for the APEC files. Default: “3.0.9” broadening (boolean, optional) – Whether or not the spectral lines should be thermally and velocity broadened. Default: True nolines (boolean, optional) – Turn off lines entirely for generating spectra. Default: False abund_table (string or array_like, optional) – The abundance table to be used for solar abundances. Either a string corresponding to a built-in table or an array of 30 floats corresponding to the abundances of each element relative to the abundance of H. 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) “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) nei (boolean, optional) – If True, use the non-equilibrium ionization tables. These are not supplied with SOXS but must be downloaded separately, in which case the apec_root parameter must also be set to their location. Default: False

Examples

>>> apec_model = ApecGenerator(0.05, 50.0, 1000, apec_vers="3.0.3",

get_nei_spectrum(kT, elem_abund, redshift, norm, velocity=0.0)[source]

Get a thermal emission spectrum assuming NEI.

Parameters: kT (float, (value, unit) tuple, or Quantity) – The temperature in keV. elem_abund (dict of element name, float pairs) – A dictionary of ionization state abundances in solar units to vary freely of the abund parameter, e.g. {“O^1”: 0.4, “O^4”: 0.6, “N^2”: 0.7} Default: None redshift (float) – The redshift. norm (float) – The normalization of the model, in the standard Xspec units of 1.0e-14*EM/(4*pi*(1+z)**2*D_A**2). velocity (float, (value, unit) tuple, or Quantity, optional) – The velocity broadening parameter, in units of km/s. Default: 0.0
get_spectrum(kT, abund, redshift, norm, velocity=0.0, elem_abund=None)[source]

Get a thermal emission spectrum assuming CIE.

Parameters: kT (float, (value, unit) tuple, or Quantity) – The temperature in keV. abund (float) – The metal abundance in solar units. redshift (float) – The redshift. norm (float) – The normalization of the model, in the standard Xspec units of 1.0e-14*EM/(4*pi*(1+z)**2*D_A**2). velocity (float, (value, unit) tuple, or Quantity, optional) – The velocity broadening parameter, in units of km/s. Default: 0.0 elem_abund (dict of element name, float pairs, optional) – A dictionary of elemental abundances in solar units to vary freely of the abund parameter, e.g. {“O”: 0.4, “N”: 0.3, “He”: 0.9}. Default: None
class soxs.spectra.ConvolvedSpectrum(spectrum, arf)[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
rescale_flux(new_flux, emin=None, emax=None, flux_type='photons')[source]

Rescale the flux of the convolved 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 “energy”: erg/s