From 827a8ffd5ca3b949215d123b40e33d62e338d5e5 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Sun, 6 Dec 2015 22:58:40 +0100 Subject: [PATCH] Update reference manual documentation. --- doc/source/reference_manual/ctbutterfly.rst | 2 +- doc/source/reference_manual/ctcubemask.rst | 32 +++++++++++++++++++++++++------- doc/source/reference_manual/cterror.rst | 22 +++++++++++++++++----- doc/source/reference_manual/cttsmap.rst | 23 +++++++++++++++++------ doc/source/reference_manual/ctulimit.rst | 7 ++++--- src/ctcubemask/ctcubemask.cpp | 2 +- src/ctcubemask/ctcubemask.par | 14 +++++++------- 7 files changed, 72 insertions(+), 30 deletions(-) diff --git a/doc/source/reference_manual/ctbutterfly.rst b/doc/source/reference_manual/ctbutterfly.rst index aa4c741..3115a30 100644 --- a/doc/source/reference_manual/ctbutterfly.rst +++ b/doc/source/reference_manual/ctbutterfly.rst @@ -46,7 +46,7 @@ General parameters Input model XML file. ``srcname [string]`` - Name of model component for which butterfly should be computed. + Name of source model for which the butterfly diagram should be computed. ``expcube [file]`` Input exposure cube file (only needed for stacked analysis). diff --git a/doc/source/reference_manual/ctcubemask.rst b/doc/source/reference_manual/ctcubemask.rst index 06245a5..9b4c60a 100644 --- a/doc/source/reference_manual/ctcubemask.rst +++ b/doc/source/reference_manual/ctcubemask.rst @@ -3,14 +3,32 @@ ctcubemask ========== -Filter a counts cube. +Mask out bins of a counts cube. Synopsis -------- This tool masks out specific regions from a counts cube by setting the -corresponding pixels to negative values. +corresponding bin values to -1. Bins with negative values will be ignored +in a maximum likelihood analysis. A mask is applied spatially and spectrally. + +ctcubemask applies a spatial mask that is comprised of a circular selection +region and a list of circular exclusion regions. The circular selection region +is specified by the sky direction of the centre and the radius of the circle. +The circular exclusion regions are specified by an ASCII file in ds9 format. +The ASCII file contains one row per exclusion region, given in the format + +``circle(83.63, 21.5, 0.4)`` + +where ``83.63`` and ``21.5`` are the Right Ascension and Declination of +the centre and ``0.4`` is the radius (in degrees) of the exclusion circle. + +ctcubemask also selects only counts cube energy layers that are fully comprised +in the energy interval specified by the ``emin`` and ``emax`` parameters. + +ctcubemask generates a counts cube FITS file that is a copy of the input +counts cube and for which all masked bins have been set to -1. General parameters @@ -19,9 +37,6 @@ General parameters ``inobs [file]`` Input counts cube or observation definition XML file. -``regfile [file]`` - Exclusion region file in ds9 format. - ``outcube [file]`` Output counts cube or observation definition XML file. @@ -41,6 +56,9 @@ General parameters ``rad [real]`` Radius of circular selection region (in degrees). +``regfile [file]`` + Input exclusion region file in ds9 format. + ``emin [real]`` Lower energy limit (in TeV). @@ -72,11 +90,11 @@ Standard parameters ``(mode = ql) [string]`` Mode of automatic parameters (default is "ql", i.e. "query and learn"). -``(logfile = ctexpcube.log) [string]`` +``(logfile = ctcubemask.log) [string]`` Name of log file. Related tools ------------- -None +:doc:`ctbin` diff --git a/doc/source/reference_manual/cterror.rst b/doc/source/reference_manual/cterror.rst index 115f6b1..d5855c5 100644 --- a/doc/source/reference_manual/cterror.rst +++ b/doc/source/reference_manual/cterror.rst @@ -3,15 +3,26 @@ cterror ======= -Computes parameter errors for a specific sky model component using -a likelihood profile method. +Computes parameter errors for a source model from the likelihood profiles. Synopsis -------- -This tool computes the parameter errors for a specific sky model using -a likelihood profile method. +This tool computes the parameter errors for a specific source model using +the likelihood profiles. Starting from the maximum likelihood model parameters, +the tool finds the minimum and maximum model parameters that lead to a decrease +of the likelihood that corresponds to a given confidence level. By default a +confidence level of 68% is used, but this level can be adjusted using the hidden +``confidence`` parameter. + +cterror generates an output model XML file that contains the values of the +best fitting model parameters. For all free parameters, an ``error`` attribute +is added that provides the statistical uncertainty in the parameter estimate +as obtained from the likelihood profile. While cterror computes asymmetrical +errors, which are written into the log file, the XML file will contain the +mean error that is obtained by computing the mean of the negative and the +positive parameter errors. General parameters @@ -24,7 +35,7 @@ General parameters Input model XML file. ``srcname [string]`` - Name of model component for which upper limit should be computed. + Name of source model for which the parameter errors should be computed. ``expcube [file]`` Input exposure cube file (only needed for stacked analysis). @@ -89,5 +100,6 @@ Standard parameters Related tools ------------- +:ref:`ctlike` :ref:`ctulimit` :ref:`ctbutterfly` diff --git a/doc/source/reference_manual/cttsmap.rst b/doc/source/reference_manual/cttsmap.rst index 259fc9e..4088482 100644 --- a/doc/source/reference_manual/cttsmap.rst +++ b/doc/source/reference_manual/cttsmap.rst @@ -3,13 +3,25 @@ cttsmap ======= -Generate a Test Statistic map. +Generate a Test Statistic (TS) map. Synopsis -------- -This tool generates a Test Statistic map. +This tool generates a Test Statistic (TS) map for a specific source model. +cttsmap works for point, radial and elliptical source models. The tool +displaces the specified source on a grid of sky directions and computes for +each direction the TS value for the model. The TS value is defined as twice +the difference between the log-likelihood obtained for the full model +(including the specified source) and the log-likelihood obtained for a model +that excludes the specified source. The square-root of the TS values +corresponds roughly to the pre-trial detection signifiance of the source (in +Gaussian sigma). + +cttsmap generates a FITS file comprising a sky map of TS values followed by +one extension per free parameter that contains sky maps of the fitted +parameter values. General parameters @@ -19,11 +31,10 @@ General parameters Input event list, counts cube or observation definition XML file. ``inmodel [file]`` - Input source model XML file. + Input model XML file. ``srcname [string]`` - Name of the source in the source model XML file for which the Test - Statistic map should be computed. + Name of source model for which the TS map should be computed. ``expcube [file]`` Input exposure cube file (only needed for stacked analysis). @@ -38,7 +49,7 @@ General parameters Calibration database. ``irf [string]`` - Response function. + Instrumental response function. ``(edisp = no) [boolean]`` Applies energy dispersion to response computation. diff --git a/doc/source/reference_manual/ctulimit.rst b/doc/source/reference_manual/ctulimit.rst index 06026bc..29e52ad 100644 --- a/doc/source/reference_manual/ctulimit.rst +++ b/doc/source/reference_manual/ctulimit.rst @@ -13,7 +13,7 @@ This tools computes the upper flux limit for a specific source model. Except of the node function, all spectral models are supported. Starting from the maximum likelihood model parameters, the tool finds the model flux that leads to a decrease of the likelihood that corresponds to a given confidence level. -By default a confidence level of 95% is used, but the level can be adjusted +By default a confidence level of 95% is used, but this level can be adjusted using the hidden ``confidence`` parameter. ctulimit writes the differential upper flux limit at a given reference @@ -33,7 +33,7 @@ General parameters Input model XML file. ``srcname [string]`` - Name of model component for which upper limit should be computed. + Name of source model for which the upper flux limit should be computed. ``expcube [file]`` Input exposure cube file (only needed for stacked analysis). @@ -113,4 +113,5 @@ Related tools ------------- :ref:`ctlike` -:ref:`cterror` \ No newline at end of file +:ref:`cterror` +:ref:`ctbutterfly` diff --git a/src/ctcubemask/ctcubemask.cpp b/src/ctcubemask/ctcubemask.cpp index b3f7691..19216a3 100644 --- a/src/ctcubemask/ctcubemask.cpp +++ b/src/ctcubemask/ctcubemask.cpp @@ -384,7 +384,7 @@ void ctcubemask::get_parameters(void) } } - // Check if radius is vaild for a RoI selection + // Check if radius is valid for a RoI selection if (m_select_roi && (*this)["rad"].is_valid()) { m_rad = (*this)["rad"].real(); } diff --git a/src/ctcubemask/ctcubemask.par b/src/ctcubemask/ctcubemask.par index 83b3e27..56669df 100644 --- a/src/ctcubemask/ctcubemask.par +++ b/src/ctcubemask/ctcubemask.par @@ -18,19 +18,19 @@ # General parameters #=================== inobs, f, a, "cntmap.fits",,, "Input counts cube or observation definition XML file" -regfile, f, a, "NONE",,, "Exclusion region file in ds9 format" outcube, f, a, "filtered_cube.fits",,, "Output counts cube or observation definition XML file" prefix, s, h, "filtered_",,, "Prefix for counts cube in observation definition XML file" # # Selection parameters #===================== -usepnt, b, h, no,,, "Use pointing instead of RA/DEC parameters?" -ra, r, a, 83.63,0,360, "RA for ROI centre (degrees)" -dec, r, a, 22.01,-90,90, "Dec for ROI centre (degrees)" -rad, r, a, 3.0,0,180, "Radius of ROI (degrees)" -emin, r, a, 0.1,,, "Lower energy limit (TeV)" -emax, r, a, 100.0,,, "Upper energy limit (TeV)" +usepnt, b, h, no,,, "Use pointing instead of RA/DEC parameters?" +ra, r, a, 83.63,0,360, "RA for ROI centre (degrees)" +dec, r, a, 22.01,-90,90, "Dec for ROI centre (degrees)" +rad, r, a, 3.0,0,180, "Radius of ROI (degrees)" +regfile, f, a, "NONE",,, "Input exclusion region file in ds9 format" +emin, r, a, 0.1,,, "Lower energy limit (TeV)" +emax, r, a, 100.0,,, "Upper energy limit (TeV)" # # Standard parameters -- libgit2 0.21.4