Working with SIMPUT Catalogs

The default storage format for unconvolved events in SOXS is SIMPUT, which is fast becoming a standard for making mock X-ray observations. SOXS provides two classes to handle SIMPUT I/O, PhotonList and SimputCatalog.

Photon Lists

Spectral and spatial models for X-ray sources can be combined to produce a list of photon coordinates and energies using the PhotonList class. Specifically, one can generate a PhotonList using the from_models() method. This requires a Spectrum for the spectral model, a SpatialModel for modeling the spatial extent of the source, an exposure time, and a flat effective area. The goal of producing a PhotonList is to generate a large sample of candidate events which can be used as a Monte-Carlo sample by either the instrument_simulator() or another tool such as MARX, SIMX, or SIXTE to produce a mock X-ray observation.

from soxs import PhotonList, PointSource, Spectrum

# Create the spectral model
spec = Spectrum.from_powerlaw(1.0, 0.01, 1.0e-2, 0.1, 10.0, 100000)
spec.apply_foreground_absorption(0.04)

# Create the spatial model
pt_src = PointSource(30.0, 45.0)

# Set the parameters
exp_time = (500.0, "ks")
area = (3.0, "m**2")

# Create the photon list
phlist = PhotonList.from_models('pt_src', spec, pt_src, exp_time, area)

In this example, we’ve given the PhotonList the name ‘pt_src’, which will be used as the prefix for any file that is written from this PhotonList. To write the photon list to a FITS file and the corresponding SIMPUT catalog file, use write_photon_list(). In this case, no SIMPUT catalog file yet exists, so a new one will be created:

simput_prefix = "my_sources"
phlist.write_photon_list(simput_prefix, overwrite=True)

Alternatively, you may already have a SIMPUT file associated with a photon list file, but want to add another source to the same SIMPUT catalog. You can accomplish this by making the same call to write_photon_list(), but setting append=True:

simput_prefix = "my_sources"
phlist.write_photon_list(simput_prefix, append=True, overwrite=True)

The files written are "my_sources_simput.fits" and "pt_src_phlist.fits".

Plotting Photon Lists

The event positions from a PhotonList can be plotted using the plot() method. This will make a scatter plot of the photon RA and Dec on the sky, optionally filtered within an energy band. For an example of how to use this method, see the Two Clusters cookbook example.

SIMPUT Catalogs

A SIMPUT catalog can be worked with directly using the SimputCatalog class. A SimputCatalog object associated with a single PhotonList can be generated using the from_models() method in the same way as the from_models() method:

from soxs import SimputCatalog, PointSource, Spectrum

# Create the spectral model
spec = Spectrum.from_powerlaw(1.0, 0.01, 1.0e-2, 0.1, 10.0, 100000)
spec.apply_foreground_absorption(0.04)

# Create the spatial model
pt_src = PointSource(30.0, 45.0)

# Set the parameters
exp_time = (500.0, "ks")
area = (3.0, "m**2")

# Create the SIMPUT catalog
sim_cat = SimputCatalog.from_models("my_sources", 'pt_src', spec, pt_src,
                                    exp_time, area)

You can write this catalog and its photon list file to disk using write_catalog():

sim_cat.write_catalog(overwrite=True)

The files written are "my_sources_simput.fits" and "pt_src_phlist.fits".

An existing SIMPUT catalog can be read in from disk using from_file():

import soxs
sim_cat = soxs.SimputCatalog.from_file("my_sources_simput.fits")

If you have one or more PhotonList objects, they can be used to create a SimputCatalog object on the fly:

import soxs
...
clusters = [cluster1, cluster2] # A list of PhotonList objects
sim_cat = soxs.SimputCatalog("clusters", clusters)

Finally, an existing PhotonList can be appended to an existing SimputCatalog using append():

import soxs

# Create the spectral model
agen = soxs.ApecGenerator(0.05, 20.0, 200000)
spec = agen.get_spectrum(4.0, 0.3, 0.05, 1.0e-3)
spec.apply_foreground_absorption(0.04)

# Create the spatial model
beta_src = BetaModel(30.0, 45.0, 20.0, 1.666667)

# Set the parameters
exp_time = (500.0, "ks")
area = (3.0, "m**2")

# Create the photon list
cluster = PhotonList.from_models('cluster', spec, beta_src, exp_time, area)

sim_cat.append(cluster)