.. _event-lists: 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 :func:`~pyxsim.photon_list.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 :math:`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 :ref:`solar-abund-tables`. * ``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, :class:`~numpy.random.RandomState` object, or :mod:`~numpy.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: .. code-block:: python n_events = pyxsim.project_photons("my_photons", "my_events", "z", (30.0, 45.0)) An off-axis projection: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python 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 :func:`~pyxsim.photon_list.project_photons`, and can be read back in using the :class:`~pyxsim.event_list.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: .. code-block:: python events = pyxsim.EventList("my_events.h5") Or, if the filenames are split into multiple numbered files, choose the first one: .. code-block:: python 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: .. code-block:: python 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: .. code-block:: python events = pyxsim.EventList("my_events*.h5") The parameters used in the run to produce the event list are stored in a ``parameters`` dictionary: .. code-block:: python print(events.parameters) .. code-block:: pycon {'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: .. code-block:: python print(events.info) .. code-block:: pycon {'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: SIMPUT ++++++ An :class:`~pyxsim.event_list.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 :ref:`instruments`). This is done by calling the :meth:`~pyxsim.event_list.EventList.write_simput_file` method: .. code-block:: python 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 :meth:`~pyxsim.event_list.EventList.write_fits_image` method: .. code-block:: python 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 :meth:`~pyxsim.event_list.EventList.write_spectrum`. .. code-block:: python 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 :func:`~pyxsim.utils.merge_files` function. This may be useful if you generate events from different sources or source types that are co-located on the sky. :func:`~pyxsim.utils.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. .. code-block:: python from pyxsim import merge_files merge_files(["events_0.h5","events_1.h5","events_3.h5"], "events.h5", overwrite=True, add_exposure_times=True)