.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _sect:ogiptospex:

OGIPtoSPEX
==========

OGIPtoSPEX is a new fortran based alternative for the trafo program.
This program converts spectra in the common OGIP format (e.g. pha,
rmf and arf) into SPEX format. Currently, it only converts one spectrum
at the time, so it does not offer sector and region control.

Some theoretical background and technical details on the SPEX file
format are given in :ref:`sect:matrices` and we refer the interested
reader to that page for full details. Here we summarise some of the
basics.

The basic philosophy behind the SPEX file format is:

.. note::
   Keep things as simple as possible unless there is absolutely no
   alternative.

Therefore, SPEX uses one file containing all the information on the
spectrum, including subtracted background, that must have the extension
*.spo* and has FITS format with well-defined extensions and columns.
Also, there is only a single file containing all the information on the
response matrix, including effective area information, that must have
the extension *.res* and also has FITS format with well-defined
extensions and columns.

.. note::
  *OGIPtoSPEX* always produces the .spo and the .res files at the same time,
  as both are linked together tightly.

Using OGIPtoSPEX
----------------

The ``ogiptospex`` program takes a number of command-line arguments. The
list of options can be called using ``ogiptospex --help``::

    user@unix:~> ogiptospex --help
    Welcome to ogiptospex!

    This is the help for program ogiptospex

    Usage:

      ogiptospex [OPTIONS]

    Options:

      --pha <input>                      Input PHA file name (required=yes)
      --rmf <input>                      Input RMF file name (required=yes)
      --bkg <input>                      Input BKG file name (required=no)
      --arf <input>                      Input ARF file name (required=no)
      --cor <input>                      Input COR file name (required=no)
      --spo <input>                      Input SPO file name (required=yes)
      --res <input>                      Input RES file name (required=yes)
      --optbin <input>                   If set, optimally bin the spectrum and response between `elow` and `ehigh` keV (required=no)
      --overwrite                        If set, output will overwrite exisiting files (required=no)

| ``--pha <input>``: The filename of the PHA source spectrum.
| ``--rmf <input>``: The filename of the RMF response matrix.
| ``--bkg <input>``: The PHA filename of the background spectrum to be subtracted (optional).
| ``--arf <input>``: The filename of the ARF effective area file (optional).
| ``--cor <input>``: The filename of the correction spectrum (optional, rarely used).
| ``--spo <input>``: The filename of the SPO output file to be written.
| ``--res <input>``: The filename of the RES output file to be written.
| ``--optbin <input>``: Optimally bin the spectrum and the response in an energy range between elow and ehigh in keV.
| ``--overwrite``: Overwrite existing files.

Examples:
'''''''''

In practice, the ogiptospex command looks like this::

    user@unix:~> ogiptospex --pha source.pha --rmf response.rmf --bkg backgr.pha --arf area.arf
                 --spo mysource.spo --res mysource.res --optbin 2.0 10.0 --overwrite

In this example, the spectrum and response are optimally binned between 2.0 and 10 keV.
If the files ``mysource.spo`` and ``mysource.res`` exist, then they will be overwritten.