Event Lists

Event lists are the main data products of pyXSIM, since they represent the synthetic observations that may be compared to and analyzed in the same fashion as real observed data. Event lists can be produced from photon list datasets by projecting along a particular axis. They can also be used to produce other useful data products.

Creating a New Event List by Projecting from a Photon List

An event list is first created from a photon list dataset using the project_photons() function. This method takes the photon list dataset, a line of sight direction, and a central position on the sky, as well as a number of additional keyword arguments to customize the resulting projection. The events are written to disk in the same way as photon lists are. The arguments are:

  • photon_prefix: The prefix of the filename(s) containing the photon list. If run in serial, the filename will be “{photon_prefix}.h5”, if run in parallel, the filenames will be “{photon_prefix}.{mpi_rank}.h5”.

  • event_prefix: The prefix of the filename(s) which will be written to contain the event list. If run in serial, the filename will be "{event_prefix}.h5", if run in parallel, the filename will be "{event_prefix}.{mpi_rank}.h5".

  • normal: The line of sight direction to project along. Accepts either a coordinate axis ("x", "y", or "z"), or a three-vector for an off-axis projection, e.g. [1.0, -0.3, 0.24].

  • sky_center: Central RA, Dec of the events in degrees.

  • absorb_model (optional): A string representing a model for foreground galactic absorption. The two models included in pyXSIM for absorption are: "wabs" (Wisconsin (Morrison and McCammon; ApJ 270, 119)), and "tbabs" (Tuebingen-Boulder (Wilms, J., Allen, A., & McCray, R. 2000, ApJ, 542, 914)). The default is no absorption–if an absorption model is chosen, the nH parameter must also be set.

  • nH (optional): The foreground galactic column density in units of \(10^{22} \rm{atoms} \rm{cm}^{-2}\), for use when one is applying foreground galactic absorption.

  • abund_table (optional): The abundance table to be used for abundances in the TBabs absorption model. Default is set in the SOXS configuration file, the default for which is "angr". Other options are "angr", "aspl", "lodd", "feld", "wilm", and "cl17.03". For the definitions of these, see Changing the Solar Abundance Table.

  • no_shifting (optional): If set to True, the photon energies will not be velocity Doppler shifted. Default False.

  • north_vector (optional): A vector defining the “up” direction, e.g. [0.0, 1.0, 0.0]. This option sets the orientation of the plane of projection. If not set, an arbitrary grid-aligned north_vector is chosen. Ignored in the case where a particular axis (e.g., “x”, “y”, or “z”) is explicitly specified.

  • sigma_pos (optional): Apply a gaussian smoothing operation to the sky positions of the events. This may be useful when the binned events appear blocky due to their uniform distribution within simulation cells. However, this will move the events away from their originating position on the sky, and so may distort surface brightness profiles and/or spectra. Should probably only be used for visualization purposes. Supply a float here to smooth with a standard deviation with this fraction of the cell or particle size. Default: None

  • flat_sky (optional): If True, we assume that the sky is “flat” and RA, Dec positions are computed using simple linear offsets, Default: False.

  • save_los (optional): If True, save the line-of-sight positions along the projection axis in units of kpc to the events list. Default: False.

  • prng (optional): An integer seed, pseudo-random number generator, RandomState object, or random (the default). Use this if you have a reason to generate the same set of random numbers, such as for a test.

This function returns the number of events generated. Example invocations could look like this:

A simple projection along an axis:

n_events = pyxsim.project_photons("my_photons", "my_events", "z",
                                  (30.0, 45.0))

An off-axis projection:

n_events = pyxsim.project_photons("my_photons", "my_events",
                                  [0.1, -0.3, 0.5], (30.0, 45.0))

An on-axis projection with absorption:

n_events = pyxsim.project_photons("my_photons", "my_events", "y",
                                  (12.0, -30.0), absorb_model="tbabs",
                                  nH=0.01)

An off-axis projection with a north_vector, without Doppler velocity shifting, and a specific random number generator:

n_events = pyxsim.project_photons("my_photons", "my_events",
                                  [0.1, -0.3, 0.5], (12.0, -30.0),
                                  no_shifting=True,
                                  north_vector=[1.0,0.0,0.0], prng=34)

Reading Event Lists from Disk

Event lists are written to disk by project_photons(), and can be read back in using the EventList class. This class facilitates various tasks for converting events to other formats.

To read in an event list, simply provide the filename if it is a single file:

events = pyxsim.EventList("my_events.h5")

Or, if the filenames are split into multiple numbered files, choose the first one:

events = pyxsim.EventList("my_events.0000.h5")

the others will be found automatically, as the total list of files is stored in the first one.

For event list files created previous to pyXSIM version 4.3.0, an event list split up into multiple files should be loaded up in one of two ways. Either the full list of files can be provided:

events = pyxsim.EventList(["my_events.0001.h5","my_events.0002.h5","my_events.0003.h5"])

or a regular expression which can be used to infer the filenames:

events = pyxsim.EventList("my_events*.h5")

The parameters used in the run to produce the event list are stored in a parameters dictionary:

print(events.parameters)

{'absoption_model': 'wabs',
 'abund_table': 'angr',
 'area': 500.0,
 'exp_time': 100000.0,
 'flat_sky': 0,
 'kernel': 'top_hat',
 'nH': 0.02,
 'no_shifting': 0,
 'normal': 'x',
 'observer': 'external',
 'sky_center': array([30., 45.])}

and other pertinent information used in the production of the event list can be found in the attached info dictionary:

print(events.info)

{'photon_file': 'plaw_photons.h5',
 'pyxsim_version': '4.1b1.dev29+g1c09873.d20221228',
 'soxs_version': 'soxs-4.2.2.dev22+gd56e1b4',
 'yt_version': '4.2.dev0'}

If this event list file has originated from merged event lists, then there will be multiple instances of each piece of information, numbered by the file, e.g. "soxs_version_0", "soxs_version_1", and so on. The original files used to make the merge will be stored in the key "original_files".

SIMPUT

An EventList can be exported to the SIMPUT file format for reading in by other packages that simulate particular instruments, such as SOXS, MARX, or SIMX (see also Producing Realistic Observations Using External Packages). This is done by calling the write_simput_file() method:

events.write_simput_file("my_great_events", overwrite=False,
                         emin=0.1, emax=9.0)

where the first argument is the prefix for the files that will be created (the SIMPUT file and a photon list sidecar file), and the other optional argument controls whether or not an existing file will be overwritten. Currently, SIMPUT files are used for export only; they cannot be used to read events back into pyXSIM.

Images

To produce a binned image, call the write_fits_image() method:

fov = (20.0, "arcmin") # the field of view / width of the image
nx = 1024 # The resolution of the image on a side
events.write_fits_image("myimage.fits", fov, nx, overwrite=True,
                        emin=0.5, emax=7.0)

which writes an image binned using the fov (width in angle) and nx (resolution) parameters to the file "myimage.fits". Set overwrite=True if the file is already there and you want to overwrite it. The emin and emax parameters control the energy range of the events which will be included in the image (default is to include all of the events).

Spectra

To produce a spectrum binned on energy, call write_spectrum().

specfile = "myspec.fits" # filename to write to
emin = 0.1 # minimum energy of spectrum
emax = 10.0 # maximum energy of spectrum
nchan = 2000 # number of bins in spectrum
events.write_spectrum(specfile, emin, emax, nchan, overwrite=False)

This bins the unconvolved event energies using the emin, emax, and nchan arguments into a histogram which will be written to the file as a spectrum. As usual, the overwrite argument determines whether or not a file can be overwritten.

Merging Event Lists

Event lists which have been written to files can be merged together, using the merge_files() function. This may be useful if you generate events from different sources or source types that are co-located on the sky.

merge_files() takes a list of input filenames, and an output filename. The optional keyword arguments are overwrite, which decides whether or not an existing file will be overwritten, and add_exposure_times decides whether or not the final file will have an exposure time of the sum of the times in the separate files or that of the longest exposure time between the files.

from pyxsim import merge_files
merge_files(["events_0.h5","events_1.h5","events_3.h5"], "events.h5",
            overwrite=True, add_exposure_times=True)