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.

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 within the same observation. So far circular and rectangular regions are supported. Circular regions are defined by 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. Rectangular regions are defined by a center, again specified by either the ra and dec or the glon and glat parameters, a width parameter, a height parameter and a posang parameter that specified the position angle measured counter clockwise from celestial North. Note that the height axis is pointing in the direction of the position angle. 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>

Finally, if bkgmethod=OFF is specified, the background regions will be taken from independent Off observations given by the inobsoff parameter. The On region can be defined in the same way as for bkgmethod=REFLECTED, and the Off regions are the corresponding regions in instrument coordinates from the Off observations.

For all background estimation methods only observations with a pointing direction at an offset smaller than maxoffset from the source are used.

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.

inobsoff [file]

Input event list or observation definition XML file for dedicated Off observations. The number of observations must be the same as for inobs.

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|RECT> [string]

Shape of the source region. CIRCLE defines a circular region around given position, RECT defines a rectangle centred on a 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).

width [real]

Width of source region rectangle (deg).

height [real]

Height of source region rectangle (deg).

posang [real]

Position angle of source region rectangle, counted counterclockwise from celestial North (deg).

srcregfile [file]

Source region file (ds9 or FITS WCS map).

bkgmethod <REFLECTED|CUSTOM|OFF> [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.

    • OFF: background is evaluated from dedicated Off observations in regions that correspond to the source region in the On observations in instrument coordinates.

bkgregfile [file]

Background regions file (ds9 or FITS WCS map).

(bkgregmin = 2) [integer]

Minimum number of background regions that are required for an observation when the REFLECTED background estimation is used. 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 region when the REFLECTED background estimation is used. 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.