# Instrument API¶

class soxs.instrument.AuxiliaryResponseFile(filename)[source]

A class for auxiliary response files (ARFs).

Parameters: filename (string) – The filename of the ARF to be read.

Examples

>>> arf = AuxiliaryResponseFile("xrs_mucal_3x10_3.0eV.arf")

detect_events(events, exp_time, flux, refband, prng=None)[source]

Use the ARF to determine a subset of photons which will be detected. Returns a boolean NumPy array which is the same is the same size as the number of photons, wherever it is “true” means those photons have been detected.

Parameters: events (dict of np.ndarrays) – The energies and positions of the photons. exp_time (float) – The exposure time in seconds. flux (float) – The total flux of the photons in erg/s/cm^2. refband (array_like) – A two-element array or list containing the limits of the energy band which the flux was computed in. 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.
classmethod from_instrument(name)[source]

Return an AuxiliaryResponseFile object from the name of an existing instrument specification in SOXS.

Parameters: name (string) – The name of the instrument specification to use to obtain the ARF object from.

Examples

>>> arf = soxs.AuxiliaryResponseFile.from_instrument("hdxi")

interpolate_area(energy)[source]

Interpolate the effective area to the energies provided by the supplied energy array.

plot(xscale='log', yscale='log', xlabel=None, ylabel=None, fig=None, ax=None, **kwargs)[source]

Make a quick plot of the effective area curve.

Parameters: xscale (string) – The scale of the x-axis. “linear” or “log”. yscale (string) – The scale of the y-axis. “linear” or “log”. xlabel (string) – The label of the x-axis. Default: “E (keV)” ylabel (string) – The label of the y-axis. Default: “$mathrm{A(cm^2)}$” fig (Figure, optional) – The figure to place the plot in. If not supplied, one will be created. ax (Axes, optional) – The axes to place the plot in. If not supplied, one will be created. other arguments are passed to the call to (All) –

:param plot().:

Returns: A tuple of the Figure and Axes objects.
class soxs.instrument.FlatResponse(emin, emax, area, nbins)[source]

A flat effective area response.

Parameters: emin (float) – The minimum energy of the response in keV. emax (float) – The maximum energy of the response in keV. area (float) – The effective area in cm**2. nbins (integer) – The number of bins in the response file.

Examples

>>> arf = FlatResponse(0.1, 10.0, 3000.0, 10000)

class soxs.instrument.RedistributionMatrixFile(filename)[source]

A class for redistribution matrix files (RMFs).

Parameters: filename (string) – The filename of the RMF to be read.

Examples

>>> rmf = RedistributionMatrixFile("xrs_hdxi.rmf")

convolve_spectrum(cspec, exp_time, prng=None)[source]
data
ebounds_data
classmethod from_instrument(name)[source]

Return an RedistributionMatrixFile object from the name of an existing instrument specification in SOXS.

Parameters: name (string) – The name of the instrument specification to use to obtain the RMF object from.

Examples

>>> arf = soxs.RedistributionMatrixFile.from_instrument("hdxi")

scatter_energies(events, prng=None)[source]

Scatter photon energies with the RMF and produce the corresponding channel values.

Parameters: events (dict of np.ndarrays) – The energies and positions of the photons. 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.
soxs.instrument.get_response_path(fn)[source]
soxs.instrument.instrument_simulator(input_events, out_file, exp_time, instrument, sky_center, overwrite=False, instr_bkgnd=True, foreground=True, ptsrc_bkgnd=True, bkgnd_file=None, no_dither=False, dither_params=None, roll_angle=0.0, subpixel_res=False, prng=None)[source]

Take unconvolved events and create an event file from them. This function calls generate_events to do the following:

1. Determines which events are observed using the ARF
2. Pixelizes the events, applying PSF effects and dithering
3. Determines energy channels using the RMF

and then calls make_background to add instrumental and astrophysical backgrounds, unless a background file is provided, in which case the background events are read from this file. The events are then written out to a file.

Parameters: input_events (string, dict, or None) – The unconvolved events to be used as input. Can be one of the following: 1. The name of a SIMPUT catalog file. 2. A Python dictionary containing the following items: “ra”: A NumPy array of right ascension values in degrees. “dec”: A NumPy array of declination values in degrees. “energy”: A NumPy array of energy values in keV. “flux”: The flux of the entire source, in units of erg/cm**2/s. out_file (string) – The name of the event file to be written. exp_time (float, (value, unit) tuple, or Quantity) – The exposure time to use, in seconds. instrument (string) – The name of the instrument to use, which picks an instrument specification from the instrument registry. sky_center (array, tuple, or list) – The center RA, Dec coordinates of the observation, in degrees. overwrite (boolean, optional) – Whether or not to overwrite an existing file with the same name. Default: False instr_bkgnd (boolean, optional) – Whether or not to include the instrumental/particle background. Default: True foreground (boolean, optional) – Whether or not to include the local foreground. Default: True ptsrc_bkgnd (boolean, optional) – Whether or not to include the point-source background. Default: True bkgnd_file (string, optional) – If set, backgrounds will be loaded from this file and not generated on the fly. Default: None no_dither (boolean, optional) – If True, turn off dithering entirely. Default: False dither_params (array-like of floats, optional) – The parameters to use to control the size and period of the dither pattern. The first two numbers are the dither amplitude in x and y detector coordinates in arcseconds, and the second two numbers are the dither period in x and y detector coordinates in seconds. Default: [8.0, 8.0, 1000.0, 707.0]. roll_angle (float, (value, unit) tuple, or Quantity, optional) – The roll angle of the observation in degrees. Default: 0.0 subpixel_res (boolean, optional) – If True, event positions are not randomized within the pixels within which they are detected. Default: False 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.

Examples

>>> instrument_simulator("sloshing_simput.fits", "sloshing_evt.fits",
...                      300000.0, "hdxi_3x10", [30., 45.], overwrite=True)

soxs.instrument.make_background_file(out_file, exp_time, instrument, sky_center, overwrite=False, foreground=True, instr_bkgnd=True, ptsrc_bkgnd=True, no_dither=False, dither_params=None, subpixel_res=False, input_sources=None, absorb_model='wabs', nH=0.05, prng=None)[source]

Make an event file consisting entirely of background events. This will be useful for creating backgrounds that can be added to simulations of sources.

Parameters: exp_time (float, (value, unit) tuple, or Quantity) – The exposure time to use, in seconds. instrument (string) – The name of the instrument to use, which picks an instrument specification from the instrument registry. sky_center (array, tuple, or list) – The center RA, Dec coordinates of the observation, in degrees. overwrite (boolean, optional) – Whether or not to overwrite an existing file with the same name. Default: False foreground (boolean, optional) – Whether or not to include the Galactic foreground. Default: True instr_bkgnd (boolean, optional) – Whether or not to include the instrumental background. Default: True ptsrc_bkgnd (boolean, optional) – Whether or not to include the point-source background. Default: True no_dither (boolean, optional) – If True, turn off dithering entirely. Default: False dither_params (array-like of floats, optional) – The parameters to use to control the size and period of the dither pattern. The first two numbers are the dither amplitude in x and y detector coordinates in arcseconds, and the second two numbers are the dither period in x and y detector coordinates in seconds. Default: [8.0, 8.0, 1000.0, 707.0]. subpixel_res (boolean, optional) – If True, event positions are not randomized within the pixels within which they are detected. Default: False input_sources (string, optional) – If set to a filename, input the point source positions, fluxes, and spectral indices from an ASCII table instead of generating them. Default: None absorb_model (string, optional) – The absorption model to use, “wabs” or “tbabs”. Default: “wabs” nH (float, optional) – The hydrogen column in units of 10**22 atoms/cm**2. Default: 0.05 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.
soxs.instrument.perform_dither(t, dither_dict)[source]
soxs.instrument.simulate_spectrum(spec, instrument, exp_time, out_file, instr_bkgnd=False, foreground=False, ptsrc_bkgnd=False, bkgnd_area=None, absorb_model='wabs', nH=0.05, overwrite=False, prng=None)[source]

Generate a PI or PHA spectrum from a Spectrum by convolving it with responses. To be used if one wants to create a spectrum without worrying about spatial response. Similar to XSPEC’s “fakeit”.

Parameters: spec (Spectrum) – The spectrum to be convolved. If None is supplied, only backgrounds will be simulated (if they are turned on). instrument (string) – The name of the instrument to use, which picks an instrument specification from the instrument registry. exp_time (float, (value, unit) tuple, or Quantity) – The exposure time in seconds. out_file (string) – The file to write the spectrum to. instr_bkgnd (boolean, optional) – Whether or not to include the instrumental/particle background. Default: False foreground (boolean, optional) – Whether or not to include the local foreground. Default: False ptsrc_bkgnd (boolean, optional) – Whether or not to include the unresolved point-source background. Default: False bkgnd_area (float, (value, unit) tuple, or Quantity) – The area on the sky for the background components, in square arcminutes. Default: None, necessary to specify if any of the background components are turned on. absorb_model (string, optional) – The absorption model to use, “wabs” or “tbabs”. Default: “wabs” nH (float, optional) – The hydrogen column in units of 10**22 atoms/cm**2. Default: 0.05 overwrite (boolean, optional) – Whether or not to overwrite an existing file. Default: False 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.

Examples

>>> spec = soxs.Spectrum.from_file("my_spectrum.txt")
>>> soxs.simulate_spectrum(spec, "lynx_lxm", 100000.0,
...                        "my_spec.pi", overwrite=True)