
csphagen
========

Creates files necessary to perform a region-based spectral On/Off analysis.


Synopsis
--------

This script generates the files that are necessary for a region-based spectral
On/Off analysis from one or several event lists. The output files are saved in
the OGIP format normally used in X-ray astronomy (PHA, ARF, RMF),
see here for a description of the format <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007/node5.html>.

If the bkgmethod parameter is REFLECTED, the script will use an On region
shape defined by the srcshape parameter and generate reflected regions by
placing regions of the same shape that are reflected with respect to the pointing
direction. So far only circular regions are supported, with a center that is
specified by the ra and dec parameters if coordsys=CEL or the glon
and glat parameters if coordsys=GAL, and a radius that is specified by the
rad parameter. Reflected regions are only generated for offset angles with
respect to the pointing direction that are smaller than the value specified by
the maxoffset parameter. If less than bkgregmin reflected regions can be
found because the offset angle between source and pointing direction is too small,
the observation will be skipped. Regions to be excluded for background
determination can be specified using a FITS mask file that is specified using the
inexclusion parameter. A mask is a sky map where all pixel values that
differ from zero will be used as exclusion region. If the FITS file
contains multiple extensions and the user does not specify which one
to use, the extention EXCLUSION will be used if available (e.g.,
if you use a skymap generated by ctskymap).
Otherwise the primary extension will be used.  

Alternatively, if bkgmethod=CUSTOM is specified, the source and background
regions will be specified using the srcregfile and bkgregfile parameters,
respectively. Both parameters accept either a ds9 region file or a sky map where
all non-zero pixel values define a region. In case that an observation definition
XML file is specified as input using the inobs, background region files can
be specified separately for each observation using the OffRegions parameter
in the format



   <observation name="Crab" id="00001" instrument="CTA">
     <parameter name="OffRegions" file="ds9.reg"/>
     ...
   </observation>

csphagen supports multiprocessing. By default each event list will be treated
in parallel over as many processes as the number of CPUs available on your
machine. The maximum number of parallel processes can be set by the user through the
nthreads hidden parameter.

The csphagen script will produce on output an observation definition XML
file that points to all relevant files. All relevant files will be prefixed with
the string specified by the prefix parameter. If several observations are
contained in the input observation definition XML file the script can either
generate region based files for each of the observations or stack all
observations into single files (controlled via the stack parameter). The
script will write out:

1) the PHA, ARF, RMF files;
2) DS9 regions files listing the source and background regions for each
   observation;
3) a new observation definition XML file.


General parameters
------------------

inobs [file]
    Input event list or observation definition XML file.

inmodel [file]
    Input model XML file (if NONE a point source at the centre of the
    source region is used).

srcname [string]
    Name of the source in the source model XML file which should be used
    for ARF computation. Only the spatial part of the model is used.

caldb [string]
    Calibration database.

irf [string]
    Instrument response function.

(inexclusion = NONE) [file]
    Optional FITS file containing a WCS map that defines sky regions
    not to be used for background estimation (where map value !=
    0). If the file contains multiple extensions the user may specify
    which one to use. Otherwise, the extention EXCLUSION will be
    used if available, or else the primary extension will be used.

outobs [file]
    Output observation definition XML file.

outmodel [file]
    Output model XML file.

(prefix = onoff) [string]
    Prefix of the file name for output PHA, ARF, RMF, XML, and DS9 region files.

ebinalg <FILE|LIN|LOG|POW> [string]
    Algorithm for defining energy bins. For FILE, the energy bins are defined
    in a FITS file that is specified by the ebinfile parameter, for LIN
    LOG and POW there will be enumbins energy bins spaced linearly,
    logarithmically, or following a power law between emin and emax,
    respectively. For POW, the parameter ebingamma specifies the slope
    of the power law.

emin [real]
    Lower energy value for first energy bin (in TeV) if LIN or LOG
    energy binning algorithms are used.

emax [real]
    Upper energy value for last energy bin (in TeV) if LIN or LOG
    energy binning algorithms are used.

enumbins [integer]
    Number of energy bins if LIN or LOG energy binning algorithms are used.
    At least 30 bins per decade are recommended for proper evaluation of the
    instrument response.

ebinfile [file]
    Name of the file containing the energy binning definition if ebinalg=FILE.
    You may use csebins to generate a file with appropriate energy binning.

ebingamma [real]
    Exponent of the power law for POW energy binning. An exponent of 1.0
    corresponds to a logarithmic energy binning.

(srcshape = CIRCLE) <CIRCLE> [string]
    Shape of the source region. So far only CIRCLE exists which defines a
    circular region around given position.

coordsys <CEL|GAL> [string]
    Coordinate system (CEL - celestial, GAL - galactic).

ra [real]
    Right Ascension of source region centre (deg).

dec [real]
    Declination of source region centre (deg).

glon [real]
    Galactic longitude of source region centre (deg).

glat [real]
    Galactic latitude of source region centre (deg).

rad [real]
    Radius of source region circle (deg).

srcregfile [file]
    Source region file (ds9 or FITS WCS map).

bkgmethod <REFLECTED|CUSTOM> [string]
    Method for background estimation:

    - REFLECTED: background is evaluated in regions with the same shape as
      the source region reflected w.r.t. pointing direction for each observation

    - CUSTOM: background is evaluated in regions specified by user. For an
      event list or a single observation in the observation definition XML file
      a region file will be queried (see bkgregfile parameter). For multiple
      observations specified in the observation definition XML file the name of
      the region file will be extracted from the OffRegions parameter that
      needs to be specified for each observation in the observation definition
      XML file. Off region files can be either ds9 region files or FITS WCS maps.

bkgregfile [file]
    Background regions file (ds9 or FITS WCS map).

(bkgregmin = 2) [integer]
    Minimum number of background regions that are required for an observation.
    If this number of background regions is not available the observation is
    skipped.

(bkgregskip = 1) [integer]
    Number of background regions that should be skipped next to the On regions.
    Typically, one region is skipped so that the Off regions are taken sufficiently
    distant from the On region, but in some cases it may be useful to keep the
    background regions next to the On region.

(use_model_bkg = yes) [boolean]
    Specifies whether the background model should be used for the computation
    of the alpha parameter and the predicted background rate in the Off
    region that is stored in the BACKRESP column of the Off spectrum when
    using the ONOFF method.

    If the parameter is set to no the background model is not used and the
    background rate is assumed identical within the On and Off regions. This
    is the classical IACT analysis method that is used when using reflected Off
    regions. In that case the alpha parameter becomes independent of energy
    and only reflects the ratio between the solid angles of the On and Off
    regions. The BACKRESP column in the Off spectrum will be filled with
    the solid angle of the On region. The data need to be fitted with the wstat
    statistic, fitting with cstat will not work.

(maxoffset = 4.0) [real]
    Maximum offset in degrees of source from camera center to accept the
    observation.

stack [boolean]
    Specifies whether multiple observations should be stacked (yes) or
    whether run-wise PHA, ARF and RMF files should be produced (no).

(etruemin = 0.01) [real]
    Minimum true energy (TeV).

(etruemax = 0.01) [real]
    Maximum true energy (TeV).

(etruebins = 30) [integer]
    Number of bins per decade for true energy bins.


Standard parameters
-------------------

(nthreads = 0) [integer]
    Number of parallel processes (0=use all available CPUs).

(chatter = 2) [integer]
    Verbosity of the executable:
     chatter = 0: no information will be logged

     chatter = 1: only errors will be logged

     chatter = 2: errors and actions will be logged

     chatter = 3: report about the task execution

     chatter = 4: detailed report about the task execution

(clobber = yes) [boolean]
    Specifies whether an existing output runlist should be overwritten.

(debug = no) [boolean]
    Enables debug mode. In debug mode the executable will dump any log file
    output to the console.

(mode = ql) [string]
    Mode of automatic parameters (default is ql, i.e. "query and learn").

(logfile = csphagen.log) [filename]
    Log filename.


Related tools or scripts
------------------------

ctskymap
csphasecrv
cslightcrv
     
