csscs

Performs spectral component separation.

Synopsis

This script performs a spectral component separation, that is, produces a flux skymap of one or multiple sources by running a likelihood analysis over multiple adjacent circular regions of interest (ROI) based on prior knowledge of the sources’ spectra. The centre of the ROIs is displaced to coincide with the centre of each pixel in the output flux map, while the radius is set through the user parameter rad.

The model fit per ROI is performed using ctlike, and only the normalisations of the model components are treated as free parameters. The script provides the possibility to fix sources other than the source(s) of interest (hidden parameter fix_srcs) or to fix the normalisation of the background model component(s) (hidden parameter fix_bkg).

The script computes the source flux and its uncertainty in each ROI/map pixel, as well as the significance of the source detection (for faster execution the significance computation can be deactivated using the hidden parameter calc_ts). Optionally, the script also computes an upper flux limit that is particularly useful in case that the source is not significantly detected within an ROI (hidden parameter calc_ulim).

The script accepts in input event lists, binned data, or observation definition XML files. Only data within an energy interval spanned by emin and emax are considered. For event lists two analysis methods are proposed: unbinned or On/Off.

For the On/Off method csphagen is used to prepare On/Off observations for every ROI analysed. In On/Off mode the user is required to provide an exclusion map to avoid using regions of significant gamma-ray emission in the evaluation of the background (exclusion maps can be generate using ctskymap). Furthemore, On/Off analysis including sources other than the source(s) of interest is not supported, and if more than one source of interest is present the response will be calculated based on the hypothesis that emission from the sources of interest is uniform over each ROI.

csscs generates a FITS file with empty primary extension. Additional extensions provide for every source of interest a skymap of flux, flux error, and, if requested, detection signficance and flux upper limits.

General parameters

inobs [file]

Input event list, counts cube or observation definition XML file.

inmodel [file]

Input model XML file.

srcnames [string]

Semicolon-separated list of names of the sources in the source model XML file which should be considered for the spectral component separation.

expcube [file]

Input exposure cube file.

psfcube [file]

Input PSF cube file.

edispcube [file]

Input energy dispersion cube file.

bkgcube [file]

Input background cube file.

caldb [string]

Calibration database.

irf [string]

Instrument response function.

inexclusion [file]

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.

(edisp = no) [boolean]

Apply energy dispersion to response computation?

outfile [file]

Output file.

nxpix [integer]

Size of the Right Ascension / Galactic longitude axis (in pixels).

nypix [integer]

Size of the Declination / Galactic latitude axis (in pixels).

binsz [real]

Pixel size (in degrees/pixel).

coordsys <CEL|GAL> [string]

Coordinate system (CEL - celestial, GAL - galactic).

proj <AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN> [string]

Projection method.

xref [real]

Right Ascension / Galactic longitude of image centre (J2000, in degrees).

yref [real]

Declination / Galactic latitude of image centre (J2000, in degrees).

rad [real]

Radius of region of interest for component separation (deg). Sets the correlation scale between neighbour pixels in the output maps. Must be at least sqrt(2) times binsz for full coverage of input data.

emin [real]

Minimum energy (in TeV).

emax [real]

Maximum energy (in TeV).

method  <UNBINNED|ONOFF> [string]

For input event lists selects between UNBINNED analysis (3D spatial/energy likelihood without binning) and ONOFF analysis (1D likelihood with background from Off regions).

(statistic = DEFAULT) <DEFAULT|CSTAT|WSTAT|CHI2> [string]

Optimization statistic. DEFAULT uses the default statistic for all observations, which is CSTAT or the statistic specified in the observation definition XML file. CSTAT uses the C statistic for all observations, WSTAT uses the W statistic for On/Off observations, and CHI2 uses the Chi squared statistic for binned or stacked observations.

(calc_ts = yes) [boolean]

Compute TS value for each map bin?

(calc_ulim = no) [boolean]

Compute upper limit for each map bin?

(fix_srcs = yes) [boolean]

Fix other sky model parameters?

(fix_bkg = no) [boolean]

Fix background model parameters?

On/Off parameters

enumbins [integer]

Number of energy bins.

(bkgmethod = REFLECTED) [string]

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

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.

width [real]

Width of source region rectangle for On/Off analysis (deg).

height [real]

Height of source region rectangle for On/Off analysis (deg).

posang [real]

Position angle of source region rectangle for On/Off analysis, counted counterclockwise from celestial North (deg).

(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 for On/Off analysis.

(etruemin = 0.01) [real]

Minimum true energy to evaluate instrumental response in On/Off analysis (TeV).

(etruemax = 0.01) [real]

Maximum true energy to evaluate instrumental response in On/Off analysis (TeV).

(etruebins = 30) [integer]

Number of bins per decade for true energy bins to evaluate instrumental response in On/Off analysis.

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 file 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 = csscs.log) [string]

Name of log file.