Events API

soxs.events.fill_regions(in_img, out_img, src_reg, bkg_val, median=False, overwrite=False, format='ds9')[source]

Fill regions which have been removed from an image (e.g. by wavdetect) with a Poisson distribution of counts, either from a single background region, a number of background regions equal to the number of source regions, or from a single background value.

Parameters:

  • in_img (string) – The file path to the input image.

  • out_img (string) – The file path to the image to be written with the filled regions.

  • src_reg (string, Region, or Regions) – The region(s) which will be filled.

  • bkg_val (float, string, Region, or Regions) – The background value(s) to use for the Poisson distribution. Can be a single value, a region, or a list of regions.

  • median (boolean) – If True, then the median value of the counts within the region will be used as the mean of the Poisson distribution

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

  • format (string, optional) – The file format specifier for the region. “ds9”, “crtf”, “fits”, etc. Default: “ds9”

soxs.events.filter_events(evtfile, newfile, region=None, emin=None, emax=None, tmin=None, tmax=None, format='ds9', exclude=False, overwrite=False)[source]
Parameters:

  • evtfile (string) – The input events file to be read in.

  • newfile (string) – The new event file that will be written.

  • region (string, Region, or Regions, optional) – The region(s) to be used for the filtering. Default: None

  • emin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be included, in keV. Default is the lowest energy available.

  • emax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be included, in keV. Default is the highest energy available.

  • tmin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be included, in seconds. Default is the earliest time available.

  • tmax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be included, in seconds. Default is the latest time available.

  • format (string, optional) – The file format specifier for the region, if supplied. “ds9”, “crtf”, “fits”, etc. Default: “ds9”

  • exclude (boolean, optional) – If True, the events in a specified region will be excluded instead of included. Default: False

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

soxs.events.make_exposure_map(event_file, expmap_file, energy, weights=None, asol_file=None, normalize=True, overwrite=False, reblock=1, nhistx=16, nhisty=16)[source]

Make an exposure map for a SOXS event file, and optionally write an aspect solution file. The exposure map will be created by binning an aspect histogram over the range of the aspect solution.

Parameters:

  • event_file (string) – The path to the event file to use for making the exposure map.

  • expmap_file (string) – The path to write the exposure map file to.

  • energy (float, (value, unit) tuple, or Quantity, or NumPy array) – The energy in keV to use when computing the exposure map, or a set of energies to be used with the weights parameter. If providing a set, it must be in keV.

  • weights (array-like, optional) – The weights to use with a set of energies given in the energy parameter. Used to create a more accurate exposure map weighted by a range of energies. Default: None

  • asol_file (string, optional) – The path to write the aspect solution file to, if desired. Default: None

  • normalize (boolean, optional) – If True, the exposure map will be divided by the exposure time so that the map’s units are cm**2. Default: True

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

  • reblock (integer, optional) – Supply an integer power of 2 here to make an exposure map with a different binning. Default: 1

  • nhistx (integer, optional) – The number of bins in the aspect histogram in the DETX direction. Default: 16

  • nhisty (integer, optional) – The number of bins in the aspect histogram in the DETY direction. Default: 16

  • order (integer, optional) – The interpolation order to use when making the exposure map. Default: 1

soxs.events.make_image(evt_file, coord_type='sky', emin=None, emax=None, tmin=None, tmax=None, bands=None, expmap_file=None, reblock=1)[source]

Generate an image by binning X-ray counts.

Parameters:

  • evt_file (string) – The name of the input event file to read.

  • coord_type (string, optional) – The type of coordinate to bin into an image. Can be “sky” or “det”. Default: “sky”

  • emin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the photons to put in the image, in keV.

  • emax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the photons to put in the image, in keV.

  • tmin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be included, in seconds. Default is the earliest time available.

  • tmax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be included, in seconds. Default is the latest time available.

  • bands (list of tuples, optional) – A list of energy bands to restrict the counts used to make the image, in the form of [(emin1, emax1), (emin2, emax2), …]. Used as an alternative to emin and emax. Default: None

  • expmap_file (string, optional) – Supply an exposure map file to divide this image by to get a flux map. Default: None

  • reblock (integer, optional) – Change this value to reblock the image to larger or small pixel sizes. Only supported for sky coordinates. Default: 1

soxs.events.merge_event_files(input_files, output_file, overwrite=False)[source]

Merge SOXS-generated event files together. The WCS used for the final file will be based on the first source file, so the original celestial coordinates for the other files will be discarded.

Parameters:

  • input_files (list of strings) – The events file(s) containing the background events.

  • output_file (string) – The merged events file.

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

soxs.events.plot_image(img_file, hdu='IMAGE', stretch='linear', vmin=None, vmax=None, facecolor='black', center=None, width=None, figsize=(10, 10), cmap=None)[source]

Plot a FITS image created by SOXS using Matplotlib.

Parameters:

  • img_file (str) – The on-disk FITS image to plot.

  • hdu (str or int, optional) – The image extension to plot. Default is “IMAGE”

  • stretch (str, optional) – The stretch to apply to the colorbar scale. Options are “linear”, “log”, and “sqrt”. Default: “linear”

  • vmin (float, optional) – The minimum value of the colorbar. If not set, it will be the minimum value in the image.

  • vmax (float, optional) – The maximum value of the colorbar. If not set, it will be the maximum value in the image.

  • facecolor (str, optional) – The color of zero-valued pixels. Default: “black”

  • center (array-like) – A 2-element object giving an (RA, Dec) coordinate for the center in degrees. If not set, the reference pixel of the image (usually the center) is used.

  • width (float, optional) – The width of the image in degrees. If not set, the width of the entire image will be used.

  • figsize (tuple, optional) – A 2-tuple giving the size of the image in inches, e.g. (12, 15). Default: (10,10)

  • cmap (str, optional) – The colormap to be used. If not set, the default Matplotlib colormap will be used.

Returns:

soxs.events.plot_spectrum(specfile, plot_energy=True, ebins=None, lw=2, xmin=None, xmax=None, ymin=None, ymax=None, xscale=None, yscale=None, label=None, fontsize=18, fig=None, ax=None, plot_counts=False, noerr=False, plot_used=False, **kwargs)[source]

Make a quick Matplotlib plot of a convolved spectrum from a file. A Matplotlib figure and axis is returned.

Parameters:

  • specfile (string) – The file to be opened for plotting.

  • plot_energy (boolean, optional) – Whether to plot in energy or channel space. Default is to plot in energy, unless the RMF for the spectrum cannot be found.

  • ebins (NumPy array, optional) – If set, these are the energy bin edges in which the spectrum will be binned. If not set, the counts will be binned according to channel. Default: None

  • lw (float, optional) – The width of the lines in the plots. Default: 2.0 px.

  • xmin (float, optional) – The left-most energy (in keV) or channel to plot. Default is the minimum value in the spectrum.

  • xmax (float, optional) – The right-most energy (in keV) or channel 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.

  • plot_counts (boolean, optional) – If set to True, the counts instead of the count rate will be plotted. Default: False

  • noerr (boolean, optional) – If True, the spectrum will be plotted without errorbars. This will always be the case if the spectrum is not noisy. Default: False

  • plot_used (boolean, optional) – If set to True, only the bins which contain more than 0 counts will be plotted. Default: False

Returns:

soxs.events.write_image(evt_file, out_file, coord_type='sky', emin=None, emax=None, tmin=None, tmax=None, bands=None, overwrite=False, expmap_file=None, reblock=1)[source]

Generate a image by binning X-ray counts and write it to a FITS file.

Parameters:

  • evt_file (string) – The name of the input event file to read.

  • out_file (string) – The name of the image file to write.

  • coord_type (string, optional) – The type of coordinate to bin into an image. Can be “sky” or “det”. Default: “sky”

  • emin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the photons to put in the image, in keV.

  • emax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the photons to put in the image, in keV.

  • tmin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be included, in seconds. Default is the earliest time available.

  • tmax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be included, in seconds. Default is the latest time available.

  • bands (list of tuples, optional) – A list of energy bands to restrict the counts used to make the image, in the form of [(emin1, emax1), (emin2, emax2), …]. Used as an alternative to emin and emax. Default: None

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

  • expmap_file (string, optional) – Supply an exposure map file to divide this image by to get a flux map. Default: None

  • reblock (integer, optional) – Change this value to reblock the image to larger or small pixel sizes. Only supported for sky coordinates. Default: 1

soxs.events.write_radial_profile(evt_file, out_file, ctr, rmin, rmax, nbins, ctr_type='celestial', emin=None, emax=None, expmap_file=None, overwrite=False)[source]

Bin up events into a radial profile and write them to a FITS table.

Parameters:

  • evt_file (string) – Input event file.

  • out_file (string) – The output file to write the profile to.

  • ctr (array-like) – The central coordinate of the profile. Can either be in celestial coordinates (the default) or “physical” pixel coordinates. If the former, the ctr_type keyword argument must be explicity set to “physical”.

  • rmin (float, (value, unit) tuple, or Quantity) – The minimum radius of the profile, in arcseconds.

  • rmax (float, (value, unit) tuple, or Quantity) – The maximum radius of the profile, in arcseconds.

  • nbins (integer) – The number of bins in the profile.

  • ctr_type (string, optional) – The type of center coordinate. Either “celestial” for (RA, Dec) coordinates (the default), or “physical” for pixel coordinates.

  • emin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be binned in keV. Default is the lowest energy available.

  • emax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be binned in keV. Default is the highest energy available.

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

  • expmap_file (string, optional) – Supply an exposure map file to determine fluxes. Default: None

soxs.events.write_spectrum(evtfile, specfile, region=None, format='ds9', exclude=False, emin=None, emax=None, tmin=None, tmax=None, overwrite=False)[source]

Bin event energies into a spectrum and write it to a FITS binary table. Does not do any grouping of channels, and will automatically determine PI or PHA. Optionally allows filtering based on time, energy, or spatial region.

Parameters:

  • evtfile (string) – The name of the event file to read the events from.

  • specfile (string) – The name of the spectrum file to be written.

  • region (string, Region, or Regions, optional) – The region(s) to be used for the filtering. Default: None

  • format (string, optional) – The file format specifier for the region. “ds9”, “crtf”, “fits”, etc. Default: “ds9”

  • exclude (boolean, optional) – If True, the events in a specified region will be excluded instead of included in the spectrum. Default: False

  • emin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be included, in keV. Default is the lowest energy available.

  • emax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be included, in keV. Default is the highest energy available.

  • tmin (float, (value, unit) tuple, or Quantity, optional) – The minimum energy of the events to be included, in seconds. Default is the earliest time available.

  • tmax (float, (value, unit) tuple, or Quantity, optional) – The maximum energy of the events to be included, in seconds. Default is the latest time available.

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