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

.. _sec:data:

Data: read response file and spectrum
=====================================

Overview
~~~~~~~~

In order to fit an observed spectrum, SPEX needs a spectral data file
and a response matrix. These data are stored in FITS format, tailored
for SPEX (see section `Response formats <#sec:resp:formats>`__). The
data files need not necessarily be located in the same directory, one
can also give a pathname plus filename in this command.

.. warning:: Filenames should be entered in the data command without their
             extension. For the files response.res and spectrum.spo, the
             data command would look like: data response spectrum.

Interfaces
~~~~~~~~~~

 - Python interface: :ref:`pyapi-data`, :ref:`pyapi-data_del`, and :ref:`pyapi-data_save`.
 - Fortran interface: :ref:`spexapi_data`, :ref:`spexapi_data_del`, and :ref:`spexapi_data_save`.

Syntax
~~~~~~

| The following syntax rules apply:
| ``data #a1 #a2`` : Read response matrix #a1 and spectrum #a2
| ``data delete instrument #i`` : Remove instrument #i from the data set
| ``data merge sum #i:`` : Merge instruments in range #i: to a single
  spectrum and response matrix, by adding the data and matrices
| ``data merge aver #i:`` : Merge instruments in range #i: to a single
  spectrum and response matrix, by averaging the data and matrices
| ``data sposave #i #a [overwrite]`` : Save data #a from instrument #i with
  the option to overwrite the existent file. No response file is saved.
| ``data ressave #i #a [overwrite]`` : Save response #a from instrument #i with
  the option to overwrite the existent file. No spectrum file is saved.
| ``data show`` : Shows the data input given, as well as the count
  (rates) for source and background, the energy range for which there is
  data the response groups and data channels. Also the integration time
  and the standard plotting options are given.
| ``data ogip`` : Reads OGIP spectra into SPEX. This command is built-up
  from sub-commands that manages the options. The ``data ogip`` command
  is given at the end to convert the input and load the spectra in SPEX.
| ``data ogip pha #a`` : Read in an OGIP PHA file (required).
| ``data ogip keypha #a``: Read in an OGIP PHA file and read the other files from the header.
| ``data ogip bkg #a`` : Read a background OGIP PHA file (optional).
| ``data ogip rmf #a`` : Read a response matrix (required).
| ``data ogip arf #a`` : Read an effective area file (optional).
| ``data ogip optbin #r:`` : Optimally bin the spectrum and response (optional).
| ``data ogip reset all`` : Reset the reading of an ogip file (if you made a mistake).
  The command requires a spectral range in keV to optimally bin.


Examples
~~~~~~~~

| ``data mosresp mosspec`` : read a spectral response file named
  mosresp.res and the corresponding spectral file mosspec.spo. Hint,
  although 2 different names are used here for ease of understanding, it
  is eased if the spectrum and response file have the same name, with
  the appropriate extension.
| ``data delete instrument 1`` : delete the first instrument
| ``data merge aver 3:5`` : merge instruments 3–5 into a single new
  instrument 3 (replacing the old instrument 3), by averaging the
  spectra. Spectra 3–5 could be spectra taken with the same instrument
  at different epochs.
| ``data merge sum 1:2`` : add spectra of instruments 1–2 into a single
  new instrument 1 (replacing the old instrument 1), by adding the
  spectra. Useful for example in combining XMM-Newton MOS1 and MOS2
  spectra.
| ``data sposave 1 mydata.spo`` : Saves the data from instrument 1 in the
  working directory under the filename of mydata.spo
| ``data ressave 1 mydata.res`` : Saves the data from instrument 1 in the
  working directory under the filename of mydata.res
| ``data /mydir/data/mosresp /mydir/data/mosspec`` : read the spectrum
  and response from the directory /mydir/data/

Loading OGIP data into SPEX works as follows::

    SPEX4> data ogip pha source.pha
    SPEX4> data ogip bkg back.pha
    SPEX4> data ogip rmf response.rmf
    SPEX4> data ogip arf area.arf
    SPEX4> data ogip optbin 1.0:10.0
    SPEX4> data ogip

After providing all the options, the final conversion and load takes place
in the final ``data ogip`` step.

One can also use the filenames in the source PHA header to read in an ogip file::

    SPEX4> data ogip keypha source.pha
    SPEX4> data ogip optbin 1.0:10.0
    SPEX4> data ogip