# Background API¶

soxs.background.instrument.add_instrumental_background(name, filename, default_focal_length)[source]

Add a particle/instrument background to the list of known backgrounds.

Parameters: name (string) – The short name of the background, which will be the key in the registry. filename (string) – The file containing the background. It must have two columns: energy in keV, and background intensity in units of photons/s/cm**2/arcmin**2/keV. default_focal_length (float, (value, unit) tuple, or Quantity) – The focal length of the telescope that this background is scaled to. Used for rescaling the background if an alternative focal length is provided in an instrument specification.
class soxs.background.spectra.BackgroundSpectrum(ebins, flux)[source]
classmethod from_spectrum(spec, fov)[source]

Create a background spectrum from a regular Spectrum object and the width of a field of view on a side.

Parameters: spec (Spectrum) – The spectrum to be used. fov (float, (value, unit) tuple, or Quantity) – The width of the field of view on a side in arcminutes.
generate_energies(t_exp, area, fov, prng=None, quiet=False)[source]

Generate photon energies from this background spectrum given an exposure time, effective area, and field of view.

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. fov (float, (value, unit) tuple, or Quantity) – The width of the field of view on a side in arcminutes. 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
to_spectrum(fov)[source]
class soxs.background.spectra.ConvolvedBackgroundSpectrum(spectrum, arf)[source]
generate_energies(t_exp, fov, prng=None, quiet=False)[source]

Generate photon energies from this convolved background spectrum given an exposure time and field of view.

Parameters: t_exp (float, (value, unit) tuple, or Quantity) – The exposure time in seconds. fov (float, (value, unit) tuple, or Quantity) – The width of the field of view on a side in arcminutes. 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
class soxs.background.spectra.InstrumentalBackgroundSpectrum(ebins, flux, default_focal_length)[source]
classmethod from_file(filename, default_focal_length)[source]

Read an instrumental background 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. default_focal_length (float, (value, unit) tuple, or Quantity) – The default focal length of the instrument in meters.
classmethod from_instrument(instr_name)[source]

Obtain an instrumental background spectrum corresponding to a registered instrument.

Parameters: instr_name (string) – Name of the instrument in the instrument registry.
generate_energies(t_exp, fov, focal_length=None, prng=None, quiet=False)[source]

Generate photon energies from this instrumental background spectrum given an exposure time, effective area, and field of view.

Parameters: t_exp (float, (value, unit) tuple, or Quantity) – The exposure time in seconds. fov (float, (value, unit) tuple, or Quantity) – The width of the field of view on a side in arcminutes. focal_length (float, (value, unit) tuple, or Quantity, optional) – The focal length in meters. Default is to use the default focal length of the instrument configuration. 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
to_scaled_spectrum(fov, focal_length=None)[source]