From 7c7ef2af93bf050e419fd2aa80c11bed4f09ebcd Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Tue, 23 Jan 2018 23:55:29 +0100 Subject: [PATCH] Update cscripts reference manual --- cscripts/cslightcrv.par | 16 ++++++++-------- cscripts/cslightcrv.py | 1 - cscripts/csresspec.par | 10 +++++----- cscripts/csroot2caldb.par | 6 +++--- cscripts/cstsmapsplit.par | 2 +- doc/source/admin/release_history/1.5.rst | 2 +- doc/source/users/reference_manual/cscaldb.rst | 24 ++++++++++++------------ doc/source/users/reference_manual/csebins.rst | 20 ++++++++++---------- doc/source/users/reference_manual/csfindobs.rst | 18 +++++++++--------- doc/source/users/reference_manual/csiactcopy.rst | 22 +++++++++++----------- doc/source/users/reference_manual/csiactdata.rst | 22 +++++++++++----------- doc/source/users/reference_manual/csiactobs.rst | 36 ++++++++++++++++++------------------ doc/source/users/reference_manual/cslightcrv.rst | 55 +++++++++++++++++++++++++++++++++++-------------------- doc/source/users/reference_manual/csmodelinfo.rst | 52 ++++++++++++++++++++++++++-------------------------- doc/source/users/reference_manual/csmodelmerge.rst | 28 ++++++++++++++-------------- doc/source/users/reference_manual/csmodelselect.rst | 32 ++++++++++++++++---------------- doc/source/users/reference_manual/csmodelsois.rst | 44 ++++++++++++++++++++++---------------------- doc/source/users/reference_manual/csobs2caldb.rst | 28 ++++++++++++++-------------- doc/source/users/reference_manual/csobsdef.rst | 60 ++++++++++++++++++++++++++++++------------------------------ doc/source/users/reference_manual/csobsinfo.rst | 53 ++++++++++++++++++++++++++--------------------------- doc/source/users/reference_manual/csobsselect.rst | 44 ++++++++++++++++++++++---------------------- doc/source/users/reference_manual/csphagen.rst | 72 ++++++++++++++++++++++++++++++++++++++---------------------------------- doc/source/users/reference_manual/csphasecrv.rst | 56 ++++++++++++++++++++++++++++++++++---------------------- doc/source/users/reference_manual/cspull.rst | 21 ++++++++++++++++----- doc/source/users/reference_manual/csresmap.rst | 16 ++++++++-------- doc/source/users/reference_manual/csresspec.rst | 78 ++++++++++++++++++++++++++++++++++++++++++------------------------------------ doc/source/users/reference_manual/csroot2caldb.rst | 28 ++++++++++++++-------------- doc/source/users/reference_manual/cssens.rst | 55 ++++++++++++++++++++++++++----------------------------- doc/source/users/reference_manual/csspec.rst | 56 ++++++++++++++++++++++++++++++++------------------------ doc/source/users/reference_manual/cssrcdetect.rst | 18 +++++++++--------- doc/source/users/reference_manual/cstsdist.rst | 3 +-- doc/source/users/reference_manual/cstsmapmerge.rst | 30 +++++++++++++++--------------- doc/source/users/reference_manual/cstsmapsplit.rst | 47 +++++++++++++++++++++++++---------------------- doc/source/users/reference_manual/csviscube.rst | 16 ++++++++-------- doc/source/users/reference_manual/ctbin.rst | 44 ++++++++++++++++++++++---------------------- doc/source/users/reference_manual/ctbkgcube.rst | 41 ++++++++++++++++++++--------------------- doc/source/users/reference_manual/ctbutterfly.rst | 38 +++++++++++++++++++------------------- doc/source/users/reference_manual/ctcubemask.rst | 24 ++++++++++++------------ doc/source/users/reference_manual/ctedispcube.rst | 42 +++++++++++++++++++++--------------------- doc/source/users/reference_manual/cterror.rst | 16 ++++++++-------- doc/source/users/reference_manual/ctexpcube.rst | 36 ++++++++++++++++++------------------ doc/source/users/reference_manual/ctlike.rst | 22 +++++++++++----------- doc/source/users/reference_manual/ctmapcube.rst | 2 +- doc/source/users/reference_manual/ctmodel.rst | 52 ++++++++++++++++++++++++++-------------------------- doc/source/users/reference_manual/ctobssim.rst | 40 ++++++++++++++++++++-------------------- doc/source/users/reference_manual/ctphase.rst | 22 +++++++++++----------- doc/source/users/reference_manual/ctprob.rst | 26 +++++++++++++------------- doc/source/users/reference_manual/ctpsfcube.rst | 42 +++++++++++++++++++++--------------------- doc/source/users/reference_manual/ctselect.rst | 44 ++++++++++++++++++++++---------------------- doc/source/users/reference_manual/ctskymap.rst | 34 +++++++++++++++++----------------- doc/source/users/reference_manual/cttsmap.rst | 16 ++++++++-------- doc/source/users/reference_manual/ctulimit.rst | 16 ++++++++-------- doc/source/users/reference_manual/index.rst | 2 +- doc/source/users/reference_manual/usage.rst | 21 ++++++++++++--------- doc/source/users/tutorials/1dc/getting_tools.rst | 2 +- doc/source/users/tutorials/beyond/beyond_residual_spectrum.rst | 2 +- doc/source/users/user_manual/introduction.rst | 69 +++++++++++++++++++++++++++++++++------------------------------------ test/test_csresspec.py | 13 +++++++------ 58 files changed, 895 insertions(+), 842 deletions(-) diff --git a/cscripts/cslightcrv.par b/cscripts/cslightcrv.par index ec4f7bf..8e2d636 100644 --- a/cscripts/cslightcrv.par +++ b/cscripts/cslightcrv.par @@ -16,14 +16,14 @@ # # Input and output parameters #============================ -inobs, f, a, events.fits,,, "Input event list or observation definition XML file" -inmodel, f, a, $CTOOLS/share/models/crab.xml,,, "Input model definition XML file" -srcname, s, a, Crab,,, "Source name" -caldb, s, a, prod2,,, "Calibration database" -irf, s, a, South_0.5h,,, "Instrument response function" -inexclusion, f, h, NONE,,, "Sky map of exclusion regions for On/Off analysis" -edisp, b, h, no,,, "Apply energy dispersion in Cube analysis?" -outfile, f, a, lightcurve.fits,,, "Output light curve file" +inobs, f, a, events.fits,,, "Input event list or observation definition XML file" +inmodel, f, a, $CTOOLS/share/models/crab.xml,,, "Input model definition XML file" +srcname, s, a, Crab,,, "Source name" +caldb, s, a, prod2,,, "Calibration database" +irf, s, a, South_0.5h,,, "Instrument response function" +inexclusion, f, h, NONE,,, "Sky map of exclusion regions for On/Off analysis" +edisp, b, h, no,,, "Apply energy dispersion in Cube analysis?" +outfile, f, a, lightcurve.fits,,, "Output light curve file" # # Script parameters diff --git a/cscripts/cslightcrv.py b/cscripts/cslightcrv.py index 0ca4547..d430d72 100755 --- a/cscripts/cslightcrv.py +++ b/cscripts/cslightcrv.py @@ -107,7 +107,6 @@ class cslightcrv(ctools.csobservation): # Set On/Off analysis flag and query relevant user parameters self._onoff = self._is_onoff() - # If cube analysis is selected # Set stacked analysis flag and query relevant user parameters if not self._onoff: self._stacked = self._is_stacked() diff --git a/cscripts/csresspec.par b/cscripts/csresspec.par index 0e8b281..f5b5904 100644 --- a/cscripts/csresspec.par +++ b/cscripts/csresspec.par @@ -32,13 +32,13 @@ outfile, f, a, resspec.fits,,, "Output residual spectrum file" # Script parameters #================== statistic, s, h, DEFAULT,DEFAULT|CSTAT|WSTAT|CHI2,, "Optimization statistic" -components,b, h, no,,, "Calculate model for individual components" -ebinalg, s, h, LOG,LIN|LOG|FILE,, "Binning algorithm" +components,b, h, no,,, "Calculate model for individual components?" +ebinalg, s, a, LOG,FILE|LIN|LOG,, "Algorithm for defining energy bins" emin, r, a, 0.1,,, "Lower energy limit (TeV)" emax, r, a, 100.0,,, "Upper energy limit (TeV)" enumbins, i, a, 20,,, "Number of model cube energy bins" ebinfile, f, a, NONE,,, "Name of the file containing the energy bin definition" -stack, b, a, no,,, "Stack observations" +stack, b, a, no,,, "Stack observations?" coordsys, s, a, CEL,CEL|GAL,, "Coordinate System" proj, s, a, CAR,AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN,, "Projection method" xref, r, a, 83.63,0,360, "First coordinate of image/source region center in degrees (RA or galactic l)" @@ -46,11 +46,11 @@ yref, r, a, 22.01,-90,90, "Second coordinate of image/source region center nxpix, i, a, 200,,, "Size of the X axis in pixels" nypix, i, a, 200,,, "Size of the Y axis in pixels" binsz, r, a, 0.02,,, "Pixel size (deg/pixel)" -mask, b, a, no,,, "Mask data to calculate residuals in ROI" +mask, b, a, no,,, "Mask data to calculate residuals in ROI?" 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" +regfile, f, a, NONE,,, "Input exclusion region file in ds9 format" algorithm, s, a, SIGNIFICANCE,SUB|SUBDIV|SUBDIVSQRT|SIGNIFICANCE,, "Residuals computation algorithm" # diff --git a/cscripts/csroot2caldb.par b/cscripts/csroot2caldb.par index 9dff400..cf97262 100644 --- a/cscripts/csroot2caldb.par +++ b/cscripts/csroot2caldb.par @@ -27,9 +27,9 @@ azimuth, r, a, 0.0,0.0,360.0, "Azimuth Angle (deg)" emin, r, h, UNDEF,,, "Minimum energy threshold (TeV)" emax, r, h, UNDEF,,, "Maximum energy threshold (TeV)" psftype, s, h, Gauss,Gauss|King,, "Point spread function type" -split, b, h, no,,, "Split IRF components into different files" -norm1d, b, h, no,,, "Normalize on 1D histograms" -rebin, b, h, no,,, "Rebin" +split, b, h, no,,, "Split IRF components into different files?" +norm1d, b, h, no,,, "Normalize on 1D histograms?" +rebin, b, h, no,,, "Rebin?" eascale, r, h, 1.0,,, "Scaling factor for effective areas" bgdscale, r, h, 1.0,,, "Scaling factor for background rates" bgdoversample, i, h, 1,,, "Spatial oversampling factor for background template" diff --git a/cscripts/cstsmapsplit.par b/cscripts/cstsmapsplit.par index 5e469f8..0c16c9c 100644 --- a/cscripts/cstsmapsplit.par +++ b/cscripts/cstsmapsplit.par @@ -27,7 +27,7 @@ caldb, s, a, prod2,,, "Calibration database" irf, s, a, South_0.5h,,, "Instrument response function" edisp, b, h, no,,, "Apply energy dispersion?" errors, b, h, no,,, "Compute/store parameter errors?" -statistic, s, h, CSTAT,CSTAT|WSTAT|CHI2,, "Optimization statistic" +statistic, s, h, DEFAULT,DEFAULT|CSTAT|WSTAT|CHI2,, "Optimization statistic" outmap, f, a, tsmap.fits,,, "Output Test Statistic map file" bins_per_job, i, a, 5,,, "Number of TS map bins per task" compute_null, b, a, yes,,,"Compute null hypothesis first?" diff --git a/doc/source/admin/release_history/1.5.rst b/doc/source/admin/release_history/1.5.rst index daa1c49..b39b584 100644 --- a/doc/source/admin/release_history/1.5.rst +++ b/doc/source/admin/release_history/1.5.rst @@ -88,4 +88,4 @@ Clean up :ref:`csspec` and :ref:`cstsdist` scripts from ``cslikelihood`` base class * [`1567 `_] - - Revise :ref:`cstsdist parameters` + Revise :ref:`cstsdist` parameters diff --git a/doc/source/users/reference_manual/cscaldb.rst b/doc/source/users/reference_manual/cscaldb.rst index e5ed2f1..9108ea1 100644 --- a/doc/source/users/reference_manual/cscaldb.rst +++ b/doc/source/users/reference_manual/cscaldb.rst @@ -3,22 +3,22 @@ cscaldb ======= -Dumps all available instrument response functions into log file. +Logs all available instrument response functions into log file. Synopsis -------- -This scripts dumps all instrument response functions that are available +This scripts logs all instrument response functions that are available in the calibration database into the log file. If you want the information -on the screen, add the ``debug=yes`` parameter. +on the screen, specify ``debug=yes``. General parameters ------------------ None - + Standard parameters ------------------- @@ -26,23 +26,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is `ql``, i.e. "query and learn"). Related tools of scripts diff --git a/doc/source/users/reference_manual/csebins.rst b/doc/source/users/reference_manual/csebins.rst index 872db86..864f3ba 100644 --- a/doc/source/users/reference_manual/csebins.rst +++ b/doc/source/users/reference_manual/csebins.rst @@ -25,7 +25,7 @@ General parameters ``caldb [string]`` Calibration database. - + ``irf [string]`` Instrumental response function. @@ -34,7 +34,7 @@ General parameters ``emin [real]`` Lower energy limit of energy boundaries (in TeV). - + ``emax [real]`` Upper energy limit of energy boundaries (in TeV). @@ -53,23 +53,23 @@ Standard parameters ``(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 energy boundaries 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csebins.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csfindobs.rst b/doc/source/users/reference_manual/csfindobs.rst index e70cf70..87972a2 100644 --- a/doc/source/users/reference_manual/csfindobs.rst +++ b/doc/source/users/reference_manual/csfindobs.rst @@ -49,7 +49,7 @@ General parameters ``dec [real]`` Declination of search region (invoke "INDEF" to avoid spatial selection). - + ``rad [real]`` Radius of search region (deg) (invoke "INDEF" or negative values to avoid spatial selection) @@ -70,23 +70,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csfindobs.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csiactcopy.rst b/doc/source/users/reference_manual/csiactcopy.rst index 437305a..5a6aa40 100644 --- a/doc/source/users/reference_manual/csiactcopy.rst +++ b/doc/source/users/reference_manual/csiactcopy.rst @@ -1,7 +1,7 @@ .. _csiactcopy: csiactcopy -=========== +========== Copies IACT data from one location to another @@ -14,7 +14,7 @@ has to be mounted before running the script. For mounting, e.g. sshfs can be use .. code-block:: bash - $ sshfs user@remote.server.com:/path/to/remote/fits /path/to/mountpoint/ + $ sshfs user@remote.server.com:/path/to/remote/fits /path/to/mountpoint/ The script can optionally take an ASCII file with a list of observation IDs as input. In this way the user can copy only a specific subset of the data. Index files and data @@ -36,7 +36,7 @@ General parameters ``prodname [string]`` Name of FITS production to download - + ``outpath [file]`` Destination path of FITS data @@ -50,23 +50,23 @@ Standard parameters ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csiactdload.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csiactdata.rst b/doc/source/users/reference_manual/csiactdata.rst index 46046f9..d07148a 100644 --- a/doc/source/users/reference_manual/csiactdata.rst +++ b/doc/source/users/reference_manual/csiactdata.rst @@ -23,34 +23,34 @@ General parameters ``datapath [string]`` Path were data are located. - + ``(master_index = master.json) [string]`` Name of master index file. - - + + Standard parameters ------------------- ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csiactdata.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csiactobs.rst b/doc/source/users/reference_manual/csiactobs.rst index 829b2b7..4e6922d 100644 --- a/doc/source/users/reference_manual/csiactobs.rst +++ b/doc/source/users/reference_manual/csiactobs.rst @@ -1,7 +1,7 @@ .. _csiactobs: csiactobs -=========== +========= Creates an observation XML file for IACTs using a list of observation IDs as input. @@ -37,8 +37,8 @@ that will be in the output XML model. If an observation that given in the input ASCII file is not available on the user machine, the script dumps a warning into the logfile and the observation is -skipped. - +skipped. + General parameters ------------------ @@ -48,16 +48,16 @@ General parameters ``prodname [string]`` Name of FITS production (Run :doc:`csiactdata` to view your options). - + ``infile [file]`` Input runlist ASCII file. ``(inmodel = NONE) [file]`` Input model XML file. - + ``outobs [file]`` Output Observation Definition XML file. - + ``outmodel [file]`` Output model XML file. @@ -66,7 +66,7 @@ General parameters ``(master_indx = master.json) [file]`` Name of master index file. - + ``(bkg_scale = yes) [boolean]`` Specifies whether the background scaling factor from the observation index file should be applied if available. @@ -82,10 +82,10 @@ General parameters ``(edisp_hiera = edisp_2d) [string]`` Hierarchy of energy disperson formats. - + ``(bkg_hiera = bkg_3d) [string]`` Hierarchy of background formats. - + ``(bkg_mod_hiera = irf|aeff|gauss) [string]`` Hierarchy of background models. @@ -107,30 +107,30 @@ General parameters ``(bkg_range_factor = 100.0) [real]`` Factor to determine range of background normalisation. - + Standard parameters ------------------- ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csiactobs.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/cslightcrv.rst b/doc/source/users/reference_manual/cslightcrv.rst index 3c6500e..0d2eff2 100644 --- a/doc/source/users/reference_manual/cslightcrv.rst +++ b/doc/source/users/reference_manual/cslightcrv.rst @@ -3,21 +3,35 @@ cslightcrv ========== -Computes a lightcurve for a given source. +Computes a light curve for a given source. Synopsis -------- -This script computes a lightcurve by performing a maximum likelihood fit +This script computes a light curve by performing a maximum likelihood fit using :doc:`ctlike` in a series of time bins. The time bins can be either specified in an ASCII file, as an interval divided into equally sized time bins, or can be taken from the Good Time Intervals of the observation(s). The format of the ASCII file is one row per time bin, each specifying the start of stop value of the bin, separated by a whitespace. The times are -given in Modified Julian Days (MJD). - -cslightcrv writes the fitted model parameters and their statistical errors +given in Modified Julian Days (MJD). + +:ref:`cslightcrv` can perform the light curve fitting in unbinned, stacked or +On/Off analysis mode; on input the script always requires unbinned data, i.e. +event list(s), since only event data retain time information for light curve +fitting. To select unbinned analysis, specify ``method=3D`` and ``enumbins=0``; +for stacked analysis specify ``method=3D`` and any positive number for ``enumbins``. +To perform the analysis in On/Off model, specify ``method=ONOFF``. + +For a stacked analysis, :ref:`cslightcrv` will query the parameters that define +the counts cube (``coordsys``, ``proj``, ``xref``, ``yref``, ``nxpix``, ``nypix``, +``binsz``) while for an On/Off analysis the script will query the parameters that +are necessary to run internally the :ref:`csphagen` script (``inexclusion``, ``coordsys``, +``xref``, ``yref``, ``srcshape``, ``rad``, ``bkgmethod``, ``bkgregmin``, ``maxoffset``, +``etruemin``, ``etruemax``, ``etruebins``). + +:ref:`cslightcrv` writes the fitted model parameters and their statistical errors in a FITS file. In addition, it computes for each time bin the statistical significance of the detection, expressed by the Test Statistics, and the upper flux limit. @@ -44,12 +58,12 @@ General parameters ``(inexclusion = NONE) [file]`` Optional FITS file containing a WCS map in the first hdu that defines sky - regions not to be used for background estimation in ``ONOFF`` analysis (where + regions not to be used for background estimation in On/Off analysis (where map value != 0). ``(edisp = no) [boolean]`` Applies energy dispersion to response computation (for ``3D`` analysis only, - energy dispersion is always taken into account in ``ONOFF`` analysis). + energy dispersion is always taken into account in On/Off analysis). ``outfile [file]`` Name of the light curve output file. @@ -90,11 +104,11 @@ General parameters ``xref [real]`` Right Ascension / Galactic longitude of image centre for ``3D`` analysis or - source region centre for ``ONOFF`` analysis (J2000, in degrees). + source region centre for On/Off analysis (J2000, in degrees). ``yref [real]`` Declination / Galactic latitude of image centre for ``3D`` analysis or - source region centre for ``ONOFF`` analysis (J2000, in degrees). + source region centre for On/Off analysis (J2000, in degrees). ``nxpix [integer]`` Size of the Right Ascension / Galactic longitude axis for ``3D`` analysis (in pixels). @@ -106,14 +120,14 @@ General parameters Pixel size for ``3D`` analysis (in degrees/pixel). ``(srcshape = CIRCLE) [string]`` - Shape of the source region for ``ONOFF`` analysis. + Shape of the source region for On/Off analysis. ``CIRCLE``: circular region around given position. ``rad [real]`` - Radius of source region circle for ``ONOFF`` analysis (deg) + Radius of source region circle for On/Off analysis (deg) ``(bkgmethod = REFLECTED) [string]`` - Method for background estimation in ``ONOFF`` analysis. + Method for background estimation in On/Off analysis. ``REFLECTED:`` background evaluated in regions with the same shape as source region reflected w.r.t. pointing direction for each observation. @@ -124,17 +138,17 @@ General parameters ``(maxoffset = 4.0) [real]`` Maximum offset in degrees of source from camera center to accept the - observation for ``ONOFF`` analysis. + observation for On/Off analysis. ``(etruemin = 0.01) [real]`` - Minimum true energy to evaluate instrumental response in ``ONOFF`` analysis (TeV). + Minimum true energy to evaluate instrumental response in On/Off analysis (TeV). ``(etruemax = 0.01) [real]`` - Maximum true energy to evaluate instrumental response in ``ONOFF`` analysis (TeV). + 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 ``ONOFF`` analysis. + response in On/Off analysis. ``(statistic = DEFAULT) [string]`` Optimization statistic. ``DEFAULT`` uses the default statistic for all @@ -174,16 +188,16 @@ Standard parameters ``chatter = 3``: report about the task execution ``chatter = 4``: detailed report about the task execution - + ``(clobber = yes) [boolean]`` Specifies whether an existing light curve 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cslightcrv.log) [filename]`` Log filename. @@ -193,3 +207,4 @@ Related tools or scripts ------------------------ :doc:`ctlike` +:doc:`csphagen` diff --git a/doc/source/users/reference_manual/csmodelinfo.rst b/doc/source/users/reference_manual/csmodelinfo.rst index 3592450..0056c04 100644 --- a/doc/source/users/reference_manual/csmodelinfo.rst +++ b/doc/source/users/reference_manual/csmodelinfo.rst @@ -3,25 +3,25 @@ csmodelinfo =========== -Dumps information about a model container into log file or on screen. +Logs information about a model container into log file or on screen. Synopsis -------- -This script provides detailled information about a given model container. -It presents the number of parameters, the number of free parameters (sub- -divided by spectral, spatial and temporal type). The tool further creates -information about any parameter that is stuck at the parameter boundaries. -This might be quite useful for debugging a fit. Finally the tool also list -the TS values of each source that was fitted, in order have a quick overview -on these quantities on the screen. +This script provides detailed information about a given model container. It +presents the number of parameters, the number of free parameters (sub-divided +by spectral, spatial and temporal type). The tool further creates information +about any parameter that is stuck at the parameter boundaries. This might be +quite useful for debugging a fit. Finally the tool also list the TS values of +each source that was fitted, in order have a quick overview on these quantities +on the screen. In addition the tool is also capable of exporting the input model XML container to a region file which is compatible to be read with ds9 or other displying tools. To create a region file, the hidden parameter "ds9file" needs to be -specified. There are quite a few further hidden parameters to steer e.g. -color, font, etc of the region file output. +specified. There are quite a few further hidden parameters to steer e.g. color, +font, etc of the region file output. General parameters @@ -36,25 +36,25 @@ General parameters ``(pnt_type=cross) [string]`` Marker type for point sources -``pnt_mark_size [integer]`` +``(pnt_mark_size=12) [integer]`` Marker size for point sources ``(show_labels=yes) [boolean]`` Add source labels? - + ``(width=2) [integer]`` Line width for regions - - ``(font=helvetica) [string]`` + +``(fontfamily=helvetica) [string]`` Font for source labels ``(fontsize=12) [integer]`` Font size for source labels -``(fonttype=normal) [string]`` +``(fontweight=normal) [string]`` Use normal or bold font? -``(fonttype2=roman) [string]`` +``(fontslant=roman) [string]`` Use roman or italic font? ``(show_ext_type=yes) [boolean]`` @@ -65,31 +65,31 @@ General parameters ``(fixed_color=magenta) [string]`` Color for sources without free parameters (any ds9 color or hex code) - - + + Standard parameters ------------------- ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csmodelinfo.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csmodelmerge.rst b/doc/source/users/reference_manual/csmodelmerge.rst index b639296..7aa2700 100644 --- a/doc/source/users/reference_manual/csmodelmerge.rst +++ b/doc/source/users/reference_manual/csmodelmerge.rst @@ -13,10 +13,10 @@ This script merges several model XML file into a single model XML file. The files are passed via the ``inmodels`` parameter. There are 4 options to specify a list of files that should be merged: -* a space-separated list of file names (e.g. ``model1.xml model2.xml``) -* a semi-colon separated list of file names (e.g. ``model1.xml;model2.xml``) -* a wildcard string (e.g. ``mymodel*.xml``) -* an ASCII file containing the file names, one file per line (e.g. ``@mymodels.txt``) +- a space-separated list of file names (e.g. ``model1.xml model2.xml``) +- a semi-colon separated list of file names (e.g. ``model1.xml;model2.xml``) +- a wildcard string (e.g. ``mymodel*.xml``) +- an ASCII file containing the file names, one file per line (e.g. ``@mymodels.txt``) Note that the "@" needs to be specified in case of an ASCII file name. It is also important to note that models with the same name cannot be appended. The @@ -32,31 +32,31 @@ General parameters ``outmodel [file]`` Output model file - - + + Standard parameters ------------------- ``(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 model 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csmodelmerge.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csmodelselect.rst b/doc/source/users/reference_manual/csmodelselect.rst index ae8088e..842ad6f 100644 --- a/doc/source/users/reference_manual/csmodelselect.rst +++ b/doc/source/users/reference_manual/csmodelselect.rst @@ -21,28 +21,28 @@ General parameters ------------------ ``inobs [file]`` - Input event list or observation definition XML file + Input event list or observation definition XML file. ``inmodel [file]`` - Input model definition XML file + Input model definition XML file. ``outmodel [file]`` - Output model definition XML file + Output model definition XML file. ``(roilimit = 4.5) [real]`` - Maximum RoI radius (degrees) + Maximum RoI radius (degrees). ``(roimargin = 0.1) [real]`` - Radial margin to be added to RoIs (degrees) + Radial margin to be added to RoIs (degrees). ``(ethres = 0.1) [real]`` - Energy threshold for source flux selection (TeV) + Energy threshold for source flux selection (TeV). ``(fluxlimit = 1.0e-12) [real]`` - Minimum source flux for selection (ph/cm2/s) + Minimum source flux for selection (ph/cm2/s). ``(tslimit = 10.0) [real]`` - Minimum Test Statistic for selection + Minimum Test Statistic for selection. ``(fit_pos = yes) [boolean]`` Fit source positions? @@ -57,24 +57,24 @@ Standard parameters ``(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 model 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csmodelselect.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csmodelsois.rst b/doc/source/users/reference_manual/csmodelsois.rst index 3dfff45..1d32d13 100644 --- a/doc/source/users/reference_manual/csmodelsois.rst +++ b/doc/source/users/reference_manual/csmodelsois.rst @@ -9,43 +9,43 @@ Generate a map cube from a subset of models in an input model. Synopsis ---------- -This tool generates a map cube from a subset of sky model components contained +This script generates a map cube from a subset of sky model components contained in an input model. A map cube is a series of sky maps, each spanned by Right -Ascension or Galactic longitude and Declination or Galactic latitude. Each -map corresponds to a specific photon energy. The energy binning of the map -cube may be either linear, logarithmic, or custom defined using an input -file. +Ascension or Galactic longitude and Declination or Galactic latitude. Each map +corresponds to a specific photon energy. The energy binning of the map cube may +be either linear, logarithmic, or custom defined using an input file. -csmodelsois generates a map cube FITS file comprising two extensions. The +:ref:`csmodelsois` generates a map cube FITS file comprising two extensions. The primary extension contains a 3-dimensional image containing the map cube values. A second extension named ``ENERGIES`` contains a binary table that defines the energy values of each map in the cube. -Optionally, csmodelsois can also output an updated model XML file in which all +Optionally, :ref:`csmodelsois` can also output an updated model XML file in which all sources from the input model XML file used to generate the map cube are replaced with an updated model that uses the generated map cube. This is done -by specifying the 'outmodel' parameter. The 'soilist' parameter specifies a -list of source names (separated by ',') to be excluded from the generated +by specifying the ``outmodel`` parameter. The ``soilist`` parameter specifies a +list of source names (separated by ``,``) to be excluded from the generated cube. + General parameters ------------------ ``inmodel [file]`` Input model XML file. -``outmodel [file]`` - Output model XML file (not generated if set to ``NONE``). - ``outcube [file]`` Output map cube file. -``soilist [string]`` - CSV list of sources to be excluded from the generated map cube. - ``(ptsrcsig = 1.0) [real]`` Sigma of Gaussian to be used for point sources (in arcmin). +``soilist [string]`` + CSV list of source names to be excluded from the generated map cube. + +``outmodel [file]`` + Output model XML file (not generated if set to ``NONE``). + ``ebinalg [string]`` Algorithm for defining energy bins. @@ -62,10 +62,10 @@ General parameters Name of the file containing the energy bin definition. ``nxpix [integer]`` - Number of cube bins in Right Ascension or Galactic longitude. + Number of map cube bins in Right Ascension or Galactic longitude. ``nypix [integer]`` - Number of cube bins in Declination or Galactic latitude. + Number of map cube bins in Declination or Galactic latitude. ``binsz [real]`` Image scale (in degrees/pixel). @@ -77,16 +77,16 @@ General parameters Projection method. ``ra [real]`` - Right Ascension of cube centre (J2000, in degrees). + Right Ascension of map cube centre (J2000, in degrees). ``dec [real]`` - Declination of cube centre (J2000, in degrees). + Declination of map cube centre (J2000, in degrees). ``glon [real]`` - Galactic longitude of cube centre (in degrees). + Galactic longitude of map cube centre (in degrees). ``glat [real]`` - Galactic latitude of cube centre (in degrees). + Galactic latitude of map cube centre (in degrees). Standard parameters @@ -114,7 +114,7 @@ Standard parameters 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csmodelsois.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/csobs2caldb.rst b/doc/source/users/reference_manual/csobs2caldb.rst index de77e1c..3dc9bd6 100644 --- a/doc/source/users/reference_manual/csobs2caldb.rst +++ b/doc/source/users/reference_manual/csobs2caldb.rst @@ -11,15 +11,15 @@ Synopsis This script creates an entry in the local calibration database from an input observation container. The caldb entry can be used for simulations -with :doc:`ctobssim` later on. On default csobs2caldb uses the first observation -in the given container. This can be modified using the hidden parameter "index" -(e.g. index=3 instructs the tool to use the third observation in the container). +with :doc:`ctobssim` later on. On default :ref:`csobs2caldb` uses the first observation +in the given container. This can be modified using the hidden parameter ``index`` +(e.g. ``index=3`` instructs the tool to use the third observation in the container). Note that for the moment, the script only works for unbinned observations which -use the latest CTA IRF format (i.e. 2D/3D FITS binary tables). +use the latest CTA IRF format (i.e. 2D/3D FITS binary tables). In particular this script might be useful for simulations of current IACT data. -Provided a specific observation with IRFs e.g. at certain zenith/azimuth angle, -the user can create a caldb entry using this tool and subsequently simulate e.g. +Provided a specific observation with IRFs e.g. at certain zenith/azimuth angle, +the user can create a caldb entry using this tool and subsequently simulate e.g. 50 hours using this configuration. General parameters @@ -50,23 +50,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csobs2caldb.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csobsdef.rst b/doc/source/users/reference_manual/csobsdef.rst index 2616476..540c8a8 100644 --- a/doc/source/users/reference_manual/csobsdef.rst +++ b/doc/source/users/reference_manual/csobsdef.rst @@ -14,28 +14,28 @@ a pointing list. The pointing list is a comma-separated value (CSV) ASCII file with header keywords in the first row followed by a list of pointings (one pointing per row). The following header keywords are supported (case sensitive, column order irrelevant): - -* name - Observation name string -* id - Unique observation identifier string -* ra - Right Ascension of pointing (deg) -* dec - Declination of pointing (deg) -* lon - Galactic longitude of pointing (deg) -* lat - Galactic latitude of pointing (deg) -* duration - Duration of pointing (seconds) -* emin - Lower energy limit (TeV) -* emax - Upper energy limit (TeV) -* rad - Radius of region of interest (deg) -* deadc - Deadtime correction factor [0-1] -* caldb - Calibration database -* irf - Response function name - + +- name - Observation name string +- id - Unique observation identifier string +- ra - Right Ascension of pointing (deg) +- dec - Declination of pointing (deg) +- lon - Galactic longitude of pointing (deg) +- lat - Galactic latitude of pointing (deg) +- duration - Duration of pointing (seconds) +- emin - Lower energy limit (TeV) +- emax - Upper energy limit (TeV) +- rad - Radius of region of interest (deg) +- deadc - Deadtime correction factor [0-1] +- caldb - Calibration database +- irf - Response function name + Only the pairs (ra,dec) or (lon,lat) are mandatory header keywords. All other keywords are optional and can be specified when calling csobsdef as user parameters. The only exception is the "duration" keyword that will automatically be queried. - + Here some usage examples: - + ``csobsdef`` Creates minimal observation definition file. @@ -62,27 +62,27 @@ General parameters ``duration [real]`` Duration of observation (in seconds). -``(name = "") [string]`` +``(name = None) [string]`` Observation name. ``(caldb = "") [string]`` Calibration database. - + ``(irf = "") [string]`` Instrumental response function. ``(emin = UNDEF) [real]`` Lower energy limit of events (in TeV). - + ``(emax = UNDEF) [real]`` Upper energy limit of events (in TeV). - + ``(rad = UNDEF) [real]`` ROI radius (in degrees). ``(deadc = 0.95) [real]`` Average deadtime correction factor. - + Standard parameters ------------------- @@ -90,23 +90,23 @@ Standard parameters ``(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 Observation Definition XML 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csobsdef.log) [string]`` Log filename. diff --git a/doc/source/users/reference_manual/csobsinfo.rst b/doc/source/users/reference_manual/csobsinfo.rst index 9240802..b064977 100644 --- a/doc/source/users/reference_manual/csobsinfo.rst +++ b/doc/source/users/reference_manual/csobsinfo.rst @@ -3,8 +3,7 @@ csobsinfo ========= -Dumps information about an observation container into log file or on -screen. +Logs information about an observation container into log file or on screen. Synopsis @@ -15,43 +14,43 @@ For IACT observations usually several observations with different configurations are combined. The script computes e.g. the overall energy range which could be an important input for :doc:`ctbin` to create a suitable energy range. In addition the script prints the pointing attributes like the average -zenith/azimuth angle. If the hidden boolean parameter "offset" is specified to -"yes", the script queries for the target position and computes the run-by-run -offset as well as its average. In the observation summary, the time range of -the observations including total ontime and (dead-time corrected) livetime is -shown. +zenith/azimuth angle. If the hidden boolean parameter ``offset`` is set to ``yes``, +the script queries for the target position and computes the run-by-run offset as +well as its average. In the observation summary, the time range of the +observations including total ontime and (dead-time corrected) livetime is shown. -The script further contains the hidden parameter "ds9file". If specified with +The script further contains the hidden parameter ``ds9file``. If specified with a file name, the tool writes out a ds9 region file including a cross for each pointing position in the sky. -When executed from within python, the script provides methods to return arrays +When executed from within Python, the script provides methods to return arrays containing observation-wise parameters. This might be useful for graphical display within a script. The following methods are implemented: -- zeniths (returning all zenith angles) -- azimuths (returning all azimuth angles) -- offsets (returning all offset angles, provided the hidden parameter offset=yes) -- ebounds (returning energy boundaries) -- gtis (returning good time intervals) + +- ``zeniths`` (return zenith angles) +- ``azimuths`` (return azimuth angles) +- ``offsets`` (return offset angles, provided the hidden parameter ``offset=yes``) +- ``ebounds`` (return energy boundaries) +- ``gti`` (return good time intervals) General parameters ------------------ ``inobs [file]`` - Event list, counts cube, or observation definition file + Event list, counts cube, or observation definition file. ``outds9file [file]`` - DS9 region file containing pointing directions + DS9 region file containing pointing directions. ``(offset = no) [file]`` - Compute offset from target to pointing positions + Compute offset from target to pointing positions. ``ra [real]`` - Target right ascension for offset computation (only queried if offset=yes) + Target right ascension for offset computation (only queried if ``offset=yes``). ``dec [real]`` - Target declination for offset computation (only queried if offset=yes) + Target declination for offset computation (only queried if ``offset=yes``). Standard parameters @@ -60,23 +59,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csobsinfo.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csobsselect.rst b/doc/source/users/reference_manual/csobsselect.rst index 2501eca..2645e08 100644 --- a/doc/source/users/reference_manual/csobsselect.rst +++ b/doc/source/users/reference_manual/csobsselect.rst @@ -19,63 +19,63 @@ General parameters ------------------ ``inobs [file]`` - Input event list or observation definition XML file + Input event list or observation definition XML file. ``outobs [file]`` - Output observation definition XML file + Output observation definition XML file. ``pntselect [string]`` - Pointing selection region shape + Pointing selection region shape. ``coordsys [string]`` - Coordinate system (CEL - celestial, GAL - galactic) + Coordinate system (CEL - celestial, GAL - galactic). ``ra [real]`` - Right Ascension of pointing selection centre (J2000, in degrees) - + Right Ascension of pointing selection centre (J2000, in degrees). + ``dec [real]`` - Declination of pointing selection centre (J2000, in degrees) + Declination of pointing selection centre (J2000, in degrees). ``glon [real]`` - Galactic longitude of pointing selection centre (degrees) - + Galactic longitude of pointing selection centre (degrees). + ``glat [real]`` - Galactic latitude of pointing selection centre (degrees) + Galactic latitude of pointing selection centre (degrees). ``rad [real]`` - Radius of selection circle (degrees) + Radius of selection circle (degrees). ``width [real]`` - Width of selection box (degrees) + Width of selection box (degrees). ``height [real]`` - Height of selection box (degrees) + Height of selection box (degrees). + - Standard parameters ------------------- ``(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 model 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") + Mode of automatic parameters (default is ``ql``, i.e. "query and learn") ``(logfile = csobsselect.log) [filename]`` Log filename diff --git a/doc/source/users/reference_manual/csphagen.rst b/doc/source/users/reference_manual/csphagen.rst index 9bcb5fe..4e2ee7e 100644 --- a/doc/source/users/reference_manual/csphagen.rst +++ b/doc/source/users/reference_manual/csphagen.rst @@ -3,8 +3,7 @@ csphagen ======== -Creates files necessary to perform a classical region-based spectral analysis -on IACT data, i.e., source and background PHA files, ARF and RMF files. +Creates files necessary to perform a region-based spectral On/Off analysis. Synopsis @@ -21,7 +20,7 @@ used in X-ray astronomy (PHA, ARF, RMF). The outputs are: 1) the PHA, ARF, RMF files, either separately for each observation, or stacked - for a set of observations, + for a set of observations; 2) DS9 regions files listing the source and background regions for each observation; 3) a new observation definition XML file. @@ -31,29 +30,29 @@ General parameters ------------------ ``inobs [file]`` - Input event list or observation definition XML file + Input event list or observation definition XML file. ``caldb [string]`` - Calibration database + Calibration database. ``irf [string]`` - Instrument response function + Instrument response function. ``(inexclusion = NONE) [file]`` Optional FITS file containing a WCS map in the first hdu that defines sky - regions not to be used for background estimation (where map value != 0) + regions not to be used for background estimation (where map value != 0). ``outobs [string]`` - Output observation definition XML file + Output observation definition XML file. ``(prefix = onoff) [string]`` - Prefix of the file name for output PHA, ARF, RMF, XML, and DS9 region files + Prefix of the file name for output PHA, ARF, RMF, XML, and DS9 region files. ``emin [real]`` - Lower energy limit (TeV) if ``LIN`` or ``LOG`` binning algorithms are used + Lower energy limit (TeV) if ``LIN`` or ``LOG`` binning algorithms are used. ``emax [real]`` - Upper energy limit (TeV) if ``LIN`` or ``LOG`` binning algorithms are used + Upper energy limit (TeV) if ``LIN`` or ``LOG`` binning algorithms are used. ``enumbins [integer]`` Number of energy bins. At least 30 bins per decade are recommended for @@ -62,35 +61,35 @@ General parameters ``ebinalg [string]`` Algorithm for defining energy bins (``FILE``: energy bounds retrieved from file, see ``ebinfile`` parameter; ``LIN``: linearly spaced energy bins; - ``LOG``: logarithmically spaced energy bins) + ``LOG``: logarithmically spaced energy bins). ``ebinfile [file]`` Name of the file containing the energy bin definition if ``FILE`` algorithm - is used + is used. ``(srcshape = CIRCLE) [string]`` - Shape of the source region (``CIRCLE``: circular region around given position) + Shape of the source region (``CIRCLE``: circular region around given position). ``coordsys [string]`` - Coordinate system (``CEL``: celestial; ``GAL``: galactic) + Coordinate system (``CEL``: celestial; ``GAL``: galactic). ``ra [real]`` - Right Ascension of source region centre (deg) + Right Ascension of source region centre (deg). ``dec [real]`` - Declination of source region centre (deg) + Declination of source region centre (deg). ``glon [real]`` - Galactic longitude of source region centre (deg) + Galactic longitude of source region centre (deg). ``glat [real]`` - Galactic latitude of source region centre (deg) + Galactic latitude of source region centre (deg). ``rad [real]`` - Radius of source region circle (deg) + Radius of source region circle (deg). ``srcregfile [file]`` - Source region file (ds9 or FITS WCS map) + Source region file (ds9 or FITS WCS map). ``bkgmethod [string]`` Method for background estimation: @@ -107,7 +106,7 @@ General parameters 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) + Background regions file (ds9 or FITS WCS map). ``(bkgregmin = 2) [integer]`` Minimum number of background regions that are required for an observation. @@ -116,20 +115,20 @@ General parameters ``(maxoffset = 4.0) [real]`` Maximum offset in degrees of source from camera center to accept the - observation + observation. ``stack [boolean]`` Specifies whether multiple observations should be stacked (``yes``) or - whether run-wise PHA, ARF and RMF files should be produced (``no``) + whether run-wise PHA, ARF and RMF files should be produced (``no``). ``(etruemin = 0.01) [real]`` - Minimum true energy (TeV) + Minimum true energy (TeV). ``(etruemax = 0.01) [real]`` - Maximum true energy (TeV) + Maximum true energy (TeV). ``(etruebins = 30) [integer]`` - Number of bins per decade for true energy bins + Number of bins per decade for true energy bins. Standard parameters @@ -138,22 +137,22 @@ Standard parameters ``(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"). @@ -161,3 +160,8 @@ Standard parameters Log filename. +Related tools or scripts +------------------------ + +None + diff --git a/doc/source/users/reference_manual/csphasecrv.rst b/doc/source/users/reference_manual/csphasecrv.rst index a7d5412..3ff3a81 100644 --- a/doc/source/users/reference_manual/csphasecrv.rst +++ b/doc/source/users/reference_manual/csphasecrv.rst @@ -12,15 +12,27 @@ Synopsis This script computes spectra by performing a maximum likelihood fit using :doc:`ctlike` in a series of phase bins for periodic sources. The input event list must have a ``PHASE`` column containing the phase values, that can be -assigned using :doc:`ctphase`. The phase bins can be -either specified in an ASCII file or as an interval divided into equally sized -phase bins. The format of the ASCII file is one row per phase bin, each -specifying the start of stop value of the phase bin, separated by a whitespace. -The phase goes from 0.0 to 1.0. +assigned using :doc:`ctphase`. The phase bins can be either specified in an ASCII +file or as an interval divided into equally sized phase bins. The format of the +ASCII file is one row per phase bin, each specifying the start of stop value of +the phase bin, separated by a whitespace. The phase goes from 0.0 to 1.0. -The script writes the fit results into a FITS file. The script -also produces one XML file per phase bin that contains the best-fit model for -that bin. +:ref:`csphasecrv` can perform the phase curve fitting in unbinned, stacked or +On/Off analysis mode; on input the script always requires unbinned data, i.e. +event list(s), since only event data retain phase information for phase curve +fitting. To select unbinned analysis, specify ``method=3D`` and ``enumbins=0``; +for stacked analysis specify ``method=3D`` and any positive number for ``enumbins``. +To perform the analysis in On/Off model, specify ``method=ONOFF``. + +For a stacked analysis, :ref:`csphasecrv` will query the parameters that define +the counts cube (``coordsys``, ``proj``, ``xref``, ``yref``, ``nxpix``, ``nypix``, +``binsz``) while for an On/Off analysis the script will query the parameters that +are necessary to run internally the :ref:`csphagen` script (``inexclusion``, ``coordsys``, +``xref``, ``yref``, ``srcshape``, ``rad``, ``bkgmethod``, ``bkgregmin``, ``maxoffset``, +``etruemin``, ``etruemax``, ``etruebins``). + +The script writes the fit results into a FITS file. The script also produces one +XML file per phase bin that contains the best-fit model for that bin. General parameters @@ -43,7 +55,7 @@ General parameters ``(inexclusion = NONE) [file]`` Optional FITS file containing a WCS map in the first hdu that defines sky - regions not to be used for background estimation in ``ONOFF`` analysis (where + regions not to be used for background estimation in On/Off analysis (where map value != 0). ``(edisp = no) [boolean]`` @@ -74,7 +86,7 @@ General parameters Upper energy limit of events (in TeV). ``enumbins [integer]`` - Number of energy bins per phase bin (0=unbinned). + Number of energy bins per phase bin (0=unbinned for ``3D`` analysis only). ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic). @@ -84,11 +96,11 @@ General parameters ``xref [real]`` Right Ascension / Galactic longitude of image centre for ``3D`` analysis or - source region centre for ``ONOFF`` analysis (J2000, in degrees). + source region centre for On/Off analysis (J2000, in degrees). ``yref [real]`` Declination / Galactic latitude of image centre for ``3D`` analysis or - source region centre for ``ONOFF`` analysis (J2000, in degrees). + source region centre for On/Off analysis (J2000, in degrees). ``nxpix [integer]`` Size of the Right Ascension / Galactic longitude axis for ``3D`` analysis (in pixels). @@ -100,35 +112,35 @@ General parameters Pixel size for ``3D`` analysis (in degrees/pixel). ``(srcshape = CIRCLE) [string]`` - Shape of the source region for ``ONOFF`` analysis. + Shape of the source region for On/Off analysis. ``CIRCLE``: circular region around given position. ``rad [real]`` - Radius of source region circle for ``ONOFF`` analysis (deg) + Radius of source region circle for On/Off analysis (deg) ``(bkgmethod = REFLECTED) [string]`` - Method for background estimation in ``ONOFF`` analysis. + Method for background estimation in On/Off analysis. ``REFLECTED:`` background evaluated in regions with the same shape as source region reflected w.r.t. pointing direction for each observation. ``(bkgregmin = 2) [integer]`` Minimum number of background regions that are required for an observation in - ``ONOFF`` analysis. If this number of background regions is not available the + On/Off analysis. If this number of background regions is not available the observation is skipped. ``(maxoffset = 4.0) [real]`` Maximum offset in degrees of source from camera center to accept the - observation for ``ONOFF`` analysis. + observation for On/Off analysis. ``(etruemin = 0.01) [real]`` - Minimum true energy to evaluate instrumental response in ``ONOFF`` analysis (TeV). + Minimum true energy to evaluate instrumental response in On/Off analysis (TeV). ``(etruemax = 0.01) [real]`` - Maximum true energy to evaluate instrumental response in ``ONOFF`` analysis (TeV). + 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 ``ONOFF`` analysis. + response in On/Off analysis. ``(statistic = DEFAULT) [string]`` Optimization statistic. ``DEFAULT`` uses the default statistic for all @@ -156,7 +168,7 @@ Standard parameters ``chatter = 3``: report about the task execution ``chatter = 4``: detailed report about the task execution - + ``(clobber = yes) [boolean]`` Specifies whether an existing light curve output file should be overwritten. @@ -165,7 +177,7 @@ Standard parameters output to the console. ``(mode = ql) [string]`` - Mode of automatic parameters (default is "ql", i.e. "query and learn"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csphasecrv.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/cspull.rst b/doc/source/users/reference_manual/cspull.rst index 559ed0b..1673986 100644 --- a/doc/source/users/reference_manual/cspull.rst +++ b/doc/source/users/reference_manual/cspull.rst @@ -11,14 +11,25 @@ Synopsis This script generates pull distributions for all free model parameters. The pull is defined as the fitted model parameter value minus the true -value, divided by the parameter error. cspull will perform ``ntrials`` +value, divided by the parameter error. :ref:`cspull` will perform ``ntrials`` statistically independent Monte Carlo simulations followed by maximum likelihood model fitting to derive the pull distribution for each free model parameter. If the model fit is unbiased and the parameters are correct, the pull distribution should follow a Gaussian centred on 0 and with a sigma parameter of 1. -cspull will generate an ASCII file in comma-separated value (CSV) format, +The script can generate pull distributions for unbinned, binned, stacked or +On/Off analyses. The script always starts from simulating an event list. If +the ``enumbins`` parameter is zero and ``onsrc=NONE`` an unbinned analysis will +be performed. If ``enumbins`` is positive and ``onsrc=NONE`` the script will +perform a binned analysis. To perform a stacked analysis, an observation definition +XML file with response cube information has to be specified for the ``inobs`` +parameter. Finally, if the ``onsrc`` parameter is set to the name of a source in +the input model (specified via the ``inmodel`` parameter), the script will perform +an On/Off analysis using the ``REFLECTED`` method and a On region radius that is +given by the ``onrad`` parameter. + +:ref:`cspull` will generate an ASCII file in comma-separated value (CSV) format, containing one row per pull. The first row is a header row providing the column names. The following rows give the pull results, one row per pull. This includes for each parameter the parameter value, error and pull. The @@ -35,7 +46,7 @@ of trials. Both scripts require matplotlib for plotting. General parameters ------------------ -``inobs [file]`` +``(inobs = NONE) [file]`` Event list, counts cube, or observation definition XML file. ``inmodel [file]`` @@ -99,7 +110,7 @@ General parameters Number of pixels for binned analysis. ``binsz [real]`` - Pixel size for binned analysis. + Pixel size for binned analysis (degrees/pixel). ``(statistic = DEFAULT) [string]`` Optimization statistic. ``DEFAULT`` uses the default statistic for all @@ -139,7 +150,7 @@ Standard parameters output to the console. ``(mode = ql) [string]`` - Mode of automatic parameters (default is "ql", i.e. "query and learn"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cspull.log) [string]`` Log filename. diff --git a/doc/source/users/reference_manual/csresmap.rst b/doc/source/users/reference_manual/csresmap.rst index 6b03ab2..13d9b2a 100644 --- a/doc/source/users/reference_manual/csresmap.rst +++ b/doc/source/users/reference_manual/csresmap.rst @@ -18,10 +18,10 @@ binning and used for residual computation. Before residual computation, the counts and model cubes are collapsed into maps by summing over all energies. Four options exist then for residual computation: -* the subtraction of the model from the counts (SUB) -* the subtraction and division by the model (SUBDIV) -* the subtraction and division by the square root of the model (SUBDIVSQRT) -* the computation of the significance using Li & Ma (SIGNIFICANCE) +- the subtraction of the model from the counts (SUB) +- the subtraction and division by the model (SUBDIV) +- the subtraction and division by the square root of the model (SUBDIVSQRT) +- the computation of the significance using Li & Ma (SIGNIFICANCE) The residual map is written into a FITS file. @@ -32,6 +32,9 @@ General parameters ``inobs [file]`` Input event list, counts cube or observation definition XML file. +``inmodel [file]`` + Input model XML file. + ``modcube [file]`` Input model cube file (generated with ctmodel). @@ -47,9 +50,6 @@ General parameters ``bkgcube [file]`` Input background cube file. -``inmodel [file]`` - Input model XML file. - ``caldb [string]`` Calibration database. @@ -135,7 +135,7 @@ Standard parameters 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csresmap.log) [string]`` Log filename. diff --git a/doc/source/users/reference_manual/csresspec.rst b/doc/source/users/reference_manual/csresspec.rst index ad7535a..f0ff920 100644 --- a/doc/source/users/reference_manual/csresspec.rst +++ b/doc/source/users/reference_manual/csresspec.rst @@ -9,19 +9,18 @@ Generates residual spectrum. Synopsis -------- -This scripts generates a residual spectrum for a given model. It works for -event lists, counts cubes, On/Off observations or observation definition files. -For event lists parameters that define the spectral binning need to -be provided so that the script can bin the data internally. The model -is then convolved with the instrumental response function for the chosen -binning (either specified by the user or intrinsic to the observations) -and used for residual computation. It is possible to compute the model -contributions from individual model components. - -If starting from event lists or count cubes, -before residual computation the 3D counts and model cubes are collapsed into -spectra by summing over all spatial direction. It is possible to specify a mask -to compute counts, model, and residuals only for a region of interest. +This scripts generates a residual spectrum for a given model. It works for event +lists, counts cubes, On/Off observations or observation definition files. For +event lists parameters that define the spectral binning need to be provided so +that the script can bin the data internally. The model is then convolved with +the instrumental response function for the chosen binning (either specified by +the user or intrinsic to the observations) and used for residual computation. It +is possible to compute the model contributions from individual model components. + +If starting from event lists or count cubes, before residual computation the 3D +counts and model cubes are collapsed into spectra by summing over all spatial +direction. It is possible to specify a mask to compute counts, model, and +residuals only for a region of interest. For On/Off observations, counts, model, and residual spectra for the Off regions are computed as well. @@ -33,10 +32,10 @@ residuals are calculated separately for each observation. Four options exist then for residual computation: -* the subtraction of the model from the counts (SUB) -* the subtraction and division by the model (SUBDIV) -* the subtraction and division by the square root of the model (SUBDIVSQRT) -* the computation of the significance using Li & Ma (SIGNIFICANCE) +- the subtraction of the model from the counts (SUB) +- the subtraction and division by the model (SUBDIV) +- the subtraction and division by the square root of the model (SUBDIVSQRT) +- the computation of the significance using Li & Ma (SIGNIFICANCE) The counts, model, and residual spectra are written into a FITS file. @@ -47,12 +46,12 @@ General parameters ``inobs [file]`` Input event list, counts cube or observation definition XML file. -``modcube [file]`` - Input model cube file (generated with ctmodel). - ``inmodel [file]`` Input model XML file. +``modcube [file]`` + Input model cube file (generated with ctmodel). + ``expcube [file]`` Input exposure cube file. @@ -75,13 +74,18 @@ General parameters Apply energy dispersion? ``outfile [file]`` - Output file. + Output residual spectrum file. + +``(statistic = DEFAULT) [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 all On/Off + observations, and ``CHI2`` uses the Chi squared statistic for all + binned or stacked observations. -``(statistic = DEFAULT) [string]`` - Optimization statistic. For On/Off observations determines how - the background counts are computed. ``DEFAULT``, i.e., ``CSTAT``, - will use the input background model. ``WSTAT`` uses the background - counts from likelihood profiling as defined for the W statistic. +``(components = no) [boolean]`` + Calculate model for individual components? ``ebinalg [string]`` Algorithm for defining energy bins. @@ -98,35 +102,37 @@ General parameters ``ebinfile [file]`` Name of the file containing the energy bin definition. -``(stack = no) [boolean]`` - Stack multiple observations for residual calculation. +``stack [boolean]`` + Stack multiple observations for residual calculation? ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic) for stacking multiple event lists. ``proj [string]`` - Projection method for stacking multiple event lists. + Projection method for stacking multiple event lists. ``xref [real]`` Right Ascension / Galactic longitude of cube centre (J2000, in degrees) for stacking multiple event lists. ``yref [real]`` - Declination / Galactic latitude of cube centre (J2000, in degrees) for stacking - multiple event lists. + Declination / Galactic latitude of cube centre (J2000, in degrees) for + stacking multiple event lists. ``nxpix [integer]`` - Number of cube bins in Right Ascension or Galactic longitude for stacking + Number of cube bins in Right Ascension or Galactic longitude for stacking multiple event lists. ``nypix [integer]`` - Number of cube bins in Declination or Galactic latitude for stacking + Number of cube bins in Declination or Galactic latitude for stacking multiple event lists. ``binsz [real]`` - Cube bin size (in degrees/pixel) for stacking - multiple event lists. + Cube bin size (in degrees/pixel) for stacking multiple event lists. + +``mask [boolean]`` + Mask data to calculate residuals in ROI? ``ra [real]`` Right Ascension of circular selection region centre (J2000, in degrees). @@ -177,7 +183,7 @@ Standard parameters 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csresspec.log) [string]`` Log filename. diff --git a/doc/source/users/reference_manual/csroot2caldb.rst b/doc/source/users/reference_manual/csroot2caldb.rst index ccf4e94..c9c5b62 100644 --- a/doc/source/users/reference_manual/csroot2caldb.rst +++ b/doc/source/users/reference_manual/csroot2caldb.rst @@ -19,7 +19,7 @@ General parameters ``infile [file]`` Input ROOT performance file file. -``(outdir = ) [string]`` +``(outdir = "") [string]`` Output CALDB directory. ``inst [string]`` @@ -46,17 +46,17 @@ General parameters ``(emax = UNDEF) [real]`` Maximum energy threshold (TeV). -``(psftype = Gauss) [string]`` +``(psftype = Gauss) [string]`` Point spread function type. ``(split = no) [boolean]`` - Split IRF components into different files. + Split IRF components into different files? ``(norm1d = no) [boolean]`` - Normalize on 1D histograms. + Normalize on 1D histograms? ``(rebin = no) [boolean]`` - Rebin. + Rebin? ``(eascale = 1.0) [real]`` Scaling factor for effective areas. @@ -71,7 +71,7 @@ General parameters Energy above which to replace background by power law (TeV). ``(bgdinfill = no) [boolean]`` - Infill of background template?. + Infill of background template? Standard parameters @@ -80,23 +80,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csroot2caldb.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/cssens.rst b/doc/source/users/reference_manual/cssens.rst index 4ea9a95..2789064 100644 --- a/doc/source/users/reference_manual/cssens.rst +++ b/doc/source/users/reference_manual/cssens.rst @@ -10,33 +10,30 @@ Synopsis -------- This script computes the differential or integrated CTA sensitivity using -maximum likelihood fitting of a test source. The differential sensitivity -is determined for a number of energy bins, the integral sensitivity is -determined for a number of energy thresholds. The test source is fitted to -simulated data using :doc:`ctlike` to determine it's detection significance -as a function of source flux. The source flux is then varied until the -source significance achieves a given level, specified by the (hidden) -significance parameter ``sigma``. To damp variations between individual -Monte Carlo simulations, a sliding average is applied in the significance -computation (controlled by hidden ``num_avg`` parameter). - -The significance is estimated using the Test Statistic value, defined as -twice the log-likelihood difference that is obtained when fitting the -simulated data with and without the test source. The simplified assumption -is made that the significance (in Gaussian sigma) is the square root of -the Test Statistic. - -cssens will generate an ASCII file in comma-separated value (CSV) format -containing the sensitivity as function of energy. The first row is a header -row providing the column names. The following rows provide the mean -logarithmic energy and the boundaries of the energy bin for which the -sensitivity was computed. They also provide the flux within the energy bin -in Crab units, in photons (ph/cm2/s) and in energy (erg/cm2/s). Finally, -the sensitivity is given as the test source spectrum evaluated at the mean -logarithmic energy multiplied by the energy squared (erg/cm2/s). - -The sensitivity can be displayed using the ``show_sensitivity.py`` script -in the example folder. Matplotlib is required to execute the script. +maximum likelihood fitting of a test source. The differential sensitivity is +determined for a number of energy bins, the integral sensitivity is determined +for a number of energy thresholds. The test source is fitted to simulated data +using :doc:`ctlike` to determine it's detection significance as a function of +source flux. The source flux is then varied until the source significance +achieves a given level, specified by the (hidden) significance parameter +``sigma``. + +The significance is estimated using the Test Statistic value, defined as twice +the log-likelihood difference that is obtained when fitting the simulated data +with and without the test source. The simplified assumption is made that the +significance (in Gaussian sigma) is the square root of the Test Statistic. + +:ref:`cssens` will generate an ASCII file in comma-separated value (CSV) format +containing the sensitivity as function of energy. The first row is a header row +providing the column names. The following rows provide the mean logarithmic +energy and the boundaries of the energy bin for which the sensitivity was +computed. They also provide the flux within the energy bin in Crab units, in +photons (ph/cm2/s) and in energy (erg/cm2/s). Finally, the sensitivity is given +as the test source spectrum evaluated at the mean logarithmic energy multiplied +by the energy squared (erg/cm2/s). + +The sensitivity can be displayed using the ``show_sensitivity.py`` script in the +example folder. Matplotlib is required to execute the script. General parameters @@ -61,7 +58,7 @@ General parameters ``(edisp = no) [boolean]`` Apply energy dispersion to response computation? -``(deadc = 0.95) [real]`` +``(deadc = 0.98) [real]`` Average deadtime correction factor. ``outfile [file]`` @@ -135,7 +132,7 @@ Standard parameters output to the console. ``(mode = ql) [string]`` - Mode of automatic parameters (default is "ql", i.e. "query and learn"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cssens.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/csspec.rst b/doc/source/users/reference_manual/csspec.rst index a79c6e3..01c24ac 100644 --- a/doc/source/users/reference_manual/csspec.rst +++ b/doc/source/users/reference_manual/csspec.rst @@ -19,23 +19,28 @@ significance of the source detection. Optionally, it also computes an upper flux limit that is particularly useful in case that the source is not significantly detected within a spectral bin (hidden parameter ``calc_ulim``). -The script works on binned and unbinned data. - -For unbinned data, the spectral binning is either defined by a FITS file -containing the energy boundaries of each bin (option ``ebinalg=FILE``) or -as ``enumbins`` bins spread linearly (option ``ebinalg=LIN``) or -logarithmically (option ``ebinalg=LOG``) from a minimum energy given by -``emin`` to a maximum energy given by ``emax``. - -For binned data, all energy bins within the counts cube that overlap with -the energy range spanned by ``emin`` and ``emax`` are considered. The number -of spectral bins is only approximately determined by the ``enumbins`` parameter. -Naturally, the script cannot create more spectral bins than the number of -energy bins that are available in the cube. Also, in case that ``enumbins`` -is smaller than the number of energy bins in the cube, the script will fit -several layers of the counts cube for each spectral bin. The number of -layers fit is determined by the total number of energy bins divided by the -``enumbins`` parameter. +There are two fundamental methods to run the script depending on the value of +the ``method`` parameter. If ``method=SLICE`` the energy interval defined by the +``emin`` and ``emax`` parameters is divided into a number of energy bins and an +independent maximum likelihood fit is performed in each of the energy bins, +while if ``method=NODES`` the spectral model will be replaced by a node function +that will be fit to all data. The latter is particularly useful if non-CTA data +should be fitted such as data from Fermi/LAT or COMPTEL. By default, ``method`` is +set to ``AUTO`` which will automatically select the method based on the input data. +For CTA-only observations ``SLICE`` will be used, otherwise ``NODES`` will be used. + +The spectral binning is either defined by a FITS file containing the energy +boundaries of each bin (option ``ebinalg=FILE``) or as ``enumbins`` bins spread +linearly (option ``ebinalg=LIN``) or logarithmically (option ``ebinalg=LOG``) +from a minimum energy, given by ``emin``, to a maximum energy, given by ``emax``. + +For binned, stacked or On/Off CTA data, all energy bins that overlap with the +energy range spanned by ``emin`` and ``emax`` are considered. The number of spectral +bins is only approximately determined by the ``enumbins`` parameter. Naturally, +:ref:`csspec` cannot create more spectral bins than the number of energy bins that +are available in the data. In case that there are more energy bins in the data +than the number of spectral bins that are requested, :ref:`csspec` will fit the +data in all energy bins that overlap with a given spectral bin simultaneously. On output, the script will provide a FITS file with the fitted source spectrum in form of a binary table. Each row corresponds to a spectral bin. @@ -44,11 +49,14 @@ the fitted flux and flux error, the Test Statistics value (option ``calc_ts=yes``), the upper flux limit (option ``calc_ulim=yes``) and the predicted number of events (only for unbinned data). +.. warning:: + The upper limit computation is not yet implemented for the ``NODES`` method. + General parameters ------------------ -``(inobs = NONE) [file]`` +``inobs [file]`` Input event list, counts cube or observation definition XML file. ``inmodel [file]`` @@ -84,11 +92,11 @@ General parameters ``method [string]`` Spectrum generation method. - ``SLICE``: Slice energy interval into ``enumbins`` independent bins. - ``NODES``: Replace spectral model by node function with ``enumbins`` nodes. - ``AUTO`` : Automatically select method based on input data. Will use - ``SLICE`` for CTA-only observations and ``NODES`` for - observations including non-CTA data. + ``SLICE`` will slice energy interval into ``enumbins`` independent bins, + ``NODES`` will replace spectral model by node function with ``enumbins`` + nodes, and ``AUTO`` will automatically select the method based on the input + data. For CTA-only observations ``SLICE`` will be used, otherwise ``NODES`` + will be used. ``emin [real]`` Lower energy limit of events (in TeV). @@ -153,7 +161,7 @@ Standard parameters output to the console. ``(mode = ql) [string]`` - Mode of automatic parameters (default is "ql", i.e. "query and learn"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csspec.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/cssrcdetect.rst b/doc/source/users/reference_manual/cssrcdetect.rst index eb0dbd2..749a922 100644 --- a/doc/source/users/reference_manual/cssrcdetect.rst +++ b/doc/source/users/reference_manual/cssrcdetect.rst @@ -61,31 +61,31 @@ General parameters ``(fit_shape = yes) [boolean]`` Enable fitting of source shapes in model definiton XML file? - + Standard parameters ------------------- ``(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 model 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cssrcdetect.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/cstsdist.rst b/doc/source/users/reference_manual/cstsdist.rst index 344e62f..8732f46 100644 --- a/doc/source/users/reference_manual/cstsdist.rst +++ b/doc/source/users/reference_manual/cstsdist.rst @@ -106,7 +106,7 @@ Standard parameters output to the console. ``(mode = ql) [string]`` - Mode of automatic parameters (default is "ql", i.e. "query and learn"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cstsdist.log) [string]`` Log filename. @@ -117,4 +117,3 @@ Related tools or scripts :doc:`ctlike` :doc:`cspull` - diff --git a/doc/source/users/reference_manual/cstsmapmerge.rst b/doc/source/users/reference_manual/cstsmapmerge.rst index 6b91c43..00c96f5 100644 --- a/doc/source/users/reference_manual/cstsmapmerge.rst +++ b/doc/source/users/reference_manual/cstsmapmerge.rst @@ -16,10 +16,10 @@ map again. Running :doc:`cttsmap` with the hidden parameters ``binmin`` and them into one FITS file. The input slices can be passed via the ``inmaps`` parameter. There are 4 options to specify a list of files that should be merged: -* a space-separated list of file names (e.g. tsmap1.fits tsmap2.fits) -* a comma-separated list of file names (e.g. tsmap1.fits,tsmap2.fits) -* a wildcard string (e.g. tsmap*.xml) -* an ASCII file containing the file names, one file per line (e.g. @mymaps.txt) +- a space-separated list of file names (e.g. tsmap1.fits tsmap2.fits) +- a comma-separated list of file names (e.g. tsmap1.fits,tsmap2.fits) +- a wildcard string (e.g. tsmap*.xml) +- an ASCII file containing the file names, one file per line (e.g. @mymaps.txt) Note that the "@" needs to be specified in case of an ASCII file name. @@ -31,37 +31,37 @@ General parameters ``outmap [file]`` Output TS map FITS file - + ``(overwrite=yes) [boolean]`` Overwrite previously filled bins? ``(delete=no) [boolean]`` Delete merged files? - - + + Standard parameters ------------------- ``(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 TS map 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cstsmapmerge.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/cstsmapsplit.rst b/doc/source/users/reference_manual/cstsmapsplit.rst index 93ddd85..b5b7cfe 100644 --- a/doc/source/users/reference_manual/cstsmapsplit.rst +++ b/doc/source/users/reference_manual/cstsmapsplit.rst @@ -3,7 +3,7 @@ cstsmapsplit ============ -Generate commands to split the Test Statistic map computation +Generate commands to split the Test Statistic map computation. Synopsis @@ -48,21 +48,24 @@ General parameters Instrumental response function. ``(edisp = no) [boolean]`` - Applies energy dispersion to response computation. + Applies energy dispersion to response computation? ``(errors = no) [boolean]`` Compute and store parameter errors? -``(statistic = CSTAT) [string]`` - Optimization statistic. ``CSTAT`` applies to all types of observations, - ``WSTAT``applies only to On/Off observations, and ``CHI2`` applies only - to binned or stacked observations. +``(statistic = DEFAULT) [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 all On/Off + observations, and ``CHI2`` uses the Chi squared statistic for all + binned or stacked observations. ``outmap [file]`` Output Test Statistic map file. ``bins_per_job [integer]`` - Number of bins of the TS map that should be computed within one command + Number of bins of the TS map that should be computed within one command. ``compute_null [boolean]`` Pre-computes the null hypothesis globally and passes the value to the @@ -78,28 +81,28 @@ General parameters ``(usepnt = no) [boolean]`` Use CTA pointing direction for map centre instead of xref/yref parameters? - + ``nxpix [integer]`` Number of map pixels in Right Ascension or Galactic longitude. - + ``nypix [integer]`` Number of map pixels in Declination or Galactic latitude. - + ``binsz [real]`` Map pixel size (in degrees/pixel). - + ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [string]`` Projection method. ``xref [real]`` Right Ascension / Galactic longitude of map centre (J2000, in degrees). - + ``yref [real]`` Declination / Galactic latitude of map centre (J2000, in degrees). - + Standard parameters ------------------- @@ -107,24 +110,24 @@ Standard parameters ``(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 TS map 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cstsmapsplit.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/csviscube.rst b/doc/source/users/reference_manual/csviscube.rst index 7419400..0378110 100644 --- a/doc/source/users/reference_manual/csviscube.rst +++ b/doc/source/users/reference_manual/csviscube.rst @@ -64,23 +64,23 @@ Standard parameters ``(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 visibility cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = csviscube.log) [filename]`` Log filename. diff --git a/doc/source/users/reference_manual/ctbin.rst b/doc/source/users/reference_manual/ctbin.rst index f0d2a1a..b5ccba7 100644 --- a/doc/source/users/reference_manual/ctbin.rst +++ b/doc/source/users/reference_manual/ctbin.rst @@ -34,46 +34,46 @@ General parameters ``outcube [file]`` Output counts cube file. - + ``ebinalg [string]`` Algorithm for defining energy bins. - + ``emin [real]`` Lower energy value for first energy bin (in TeV). - + ``emax [real]`` Upper energy value for last energy bin (in TeV). - + ``enumbins [integer]`` Number of energy bins. - + ``ebinfile [file]`` Name of the file containing the energy bin definition. - + ``(usepnt = no) [boolean]`` Use CTA pointing direction for cube centre instead of xref/yref parameters? - + ``nxpix [integer]`` Number of cube bins in Right Ascension or Galactic longitude. - + ``nypix [integer]`` Number of cube bins in Declination or Galactic latitude. - + ``binsz [real]`` Cube bin size (in degrees/pixel). - + ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [string]`` Projection method. - + ``xref [real]`` Right Ascension / Galactic longitude of cube centre (J2000, in degrees). - + ``yref [real]`` Declination / Galactic latitude of cube centre (J2000, in degrees). - + Standard parameters ------------------- @@ -84,23 +84,23 @@ Standard parameters ``(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 counts cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctbin.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctbkgcube.rst b/doc/source/users/reference_manual/ctbkgcube.rst index 1e992ed..400009e 100644 --- a/doc/source/users/reference_manual/ctbkgcube.rst +++ b/doc/source/users/reference_manual/ctbkgcube.rst @@ -47,7 +47,6 @@ as spectral component, but you can replace this by any component of your choice. - General parameters ------------------ @@ -74,16 +73,16 @@ General parameters ``ebinalg [string]`` Algorithm for defining energy bins. - + ``emin [real]`` Lower energy value for first energy bin (in TeV). - + ``emax [real]`` Upper energy value for last energy bin (in TeV). - + ``enumbins [integer]`` Number of energy bins. - + ``ebinfile [file]`` Name of the file containing the energy bin definition. @@ -92,28 +91,28 @@ General parameters ``(usepnt = no) [boolean]`` Use CTA pointing direction for cube centre instead of xref/yref parameters? - + ``nxpix [integer]`` Number of cube bins in Right Ascension or Galactic longitude. - + ``nypix [integer]`` Number of cube bins in Declination or Galactic latitude. - + ``binsz [real]`` Cube bin size (in degrees/pixel). - + ``coordsysL [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [string]`` Projection method. - + ``xref [real]`` Right Ascension / Galactic longitude of cube centre (J2000, in degrees). - + ``yref [real]`` Declination / Galactic latitude of cube centre (J2000, in degrees). - + Standard parameters ------------------- @@ -124,23 +123,23 @@ Standard parameters ``(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 background cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctbkgcube.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctbutterfly.rst b/doc/source/users/reference_manual/ctbutterfly.rst index 655cf0f..5a229af 100644 --- a/doc/source/users/reference_manual/ctbutterfly.rst +++ b/doc/source/users/reference_manual/ctbutterfly.rst @@ -31,10 +31,10 @@ ctbutterfly writes the butterfly diagram into an ASCII file with 4 columns separated by a whitespace. Each row in the result file corresponds to a specific energy. The meaning of the columns are: -* Energy in MeV -* Fitted intensity for that energy in ph/cm2/s/MeV -* Minimum intensity for that energy in ph/cm2/s/MeV -* Maximum intensity for that energy in ph/cm2/s/MeV +- Energy in MeV +- Fitted intensity for that energy in ph/cm2/s/MeV +- Minimum intensity for that energy in ph/cm2/s/MeV +- Maximum intensity for that energy in ph/cm2/s/MeV The butterfly diagram can be displayed using the ``show_butterfly.py`` script in the example folder. @@ -45,13 +45,13 @@ General parameters ``inobs [file]`` Input event list, counts cube or observation definition XML file. - + ``inmodel [file]`` Input model XML file. - + ``srcname [string]`` Name of source model for which the butterfly diagram should be computed. - + ``expcube [file]`` Input exposure cube file. @@ -66,16 +66,16 @@ General parameters ``caldb [string]`` Calibration database. - + ``irf [string]`` Instrumental response function. ``(edisp = no) [boolean]`` Applies energy dispersion to response computation. - + ``outfile [file]`` Output butterfly ASCII file name. - + ``(fit = no) [boolean]`` Performs maximum likelihood fitting of input model ignoring any provided covariance matrix. @@ -85,7 +85,7 @@ General parameters ``(confidence = 0.68) [real]`` Confidence level for error computation. - + ``(statistic = DEFAULT) [string]`` Optimization statistic. ``DEFAULT`` uses the default statistic for all observations, which is ``CSTAT`` or the statistic specified in the @@ -119,23 +119,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctbutterfly.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctcubemask.rst b/doc/source/users/reference_manual/ctcubemask.rst index 5e5c8f8..df4af6b 100644 --- a/doc/source/users/reference_manual/ctcubemask.rst +++ b/doc/source/users/reference_manual/ctcubemask.rst @@ -46,10 +46,10 @@ General parameters ``(usepnt = no) [boolean]`` Use CTA pointing direction instead of ra/dec parameters? - + ``ra [real]`` Right Ascension of circular selection region centre (J2000, in degrees). - + ``dec [real]`` Declination of circular selection region centre (J2000, in degrees). @@ -61,10 +61,10 @@ General parameters ``emin [real]`` Lower energy limit (in TeV). - + ``emax [real]`` Upper energy limit (in TeV). - + Standard parameters ------------------- @@ -75,23 +75,23 @@ Standard parameters ``(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 counts cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctcubemask.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctedispcube.rst b/doc/source/users/reference_manual/ctedispcube.rst index 4866089..d0bbc66 100644 --- a/doc/source/users/reference_manual/ctedispcube.rst +++ b/doc/source/users/reference_manual/ctedispcube.rst @@ -57,52 +57,52 @@ General parameters ``ebinalg [string]`` Algorithm for defining energy bins. - + ``emin [real]`` Lower energy value for first energy bin (in TeV). - + ``emax [real]`` Upper energy value for last energy bin (in TeV). - + ``enumbins [integer]`` Number of energy bins. - + ``ebinfile [file]`` Name of the file containing the energy bin definition. - + ``(addbounds = no) [boolean]`` Add energies to the energy dispersion cube at the observation energy boundaries? ``(usepnt = no) [boolean]`` Use CTA pointing direction for cube centre instead of xref/yref parameters? - + ``nxpix [integer]`` Number of cube bins in Right Ascension or Galactic longitude. - + ``nypix [integer]`` Number of cube bins in Declination or Galactic latitude. - + ``binsz [real]`` Cube bin size (in degrees/pixel). - + ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [string]`` Projection method. ``xref [real]`` Right Ascension / Galactic longitude of cube centre (J2000, in degrees). - + ``yref [real]`` Declination / Galactic latitude of cube centre (J2000, in degrees). - + ``(migramax = 2.0) [real]`` Upper bound of ratio between reconstructed and true photon energy. ``(migrabins = 100) [integer]`` Number of migration bins. - + Standard parameters ------------------- @@ -110,23 +110,23 @@ Standard parameters ``(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 energy dispersion cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctedispcube.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/cterror.rst b/doc/source/users/reference_manual/cterror.rst index d663a55..fadd50e 100644 --- a/doc/source/users/reference_manual/cterror.rst +++ b/doc/source/users/reference_manual/cterror.rst @@ -86,23 +86,23 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cterror.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctexpcube.rst b/doc/source/users/reference_manual/ctexpcube.rst index 9241397..92393c5 100644 --- a/doc/source/users/reference_manual/ctexpcube.rst +++ b/doc/source/users/reference_manual/ctexpcube.rst @@ -64,16 +64,16 @@ General parameters ``ebinalg [string]`` Algorithm for defining energy bins. - + ``emin [real]`` Lower energy value for first energy bin (in TeV). - + ``emax [real]`` Upper energy value for last energy bin (in TeV). - + ``enumbins [integer]`` Number of energy bins. - + ``ebinfile [file]`` Name of the file containing the energy bin definition. @@ -82,25 +82,25 @@ General parameters ``(usepnt = no) [boolean]`` Use CTA pointing direction for cube centre instead of xref/yref parameters? - + ``nxpix [integer]`` Number of cube bins in Right Ascension or Galactic longitude. - + ``nypix [integer]`` Number of cube bins in Declination or Galactic latitude. - + ``binsz [real]`` Cube bin size (in degrees/pixel). - + ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [string]`` Projection method. ``xref [real]`` Right Ascension / Galactic longitude of cube centre (J2000, in degrees). - + ``yref [real]`` Declination / Galactic latitude of cube centre (J2000, in degrees). @@ -114,23 +114,23 @@ Standard parameters ``(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 exposure cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctexpcube.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctlike.rst b/doc/source/users/reference_manual/ctlike.rst index 48d9f0e..8e18e60 100644 --- a/doc/source/users/reference_manual/ctlike.rst +++ b/doc/source/users/reference_manual/ctlike.rst @@ -65,7 +65,7 @@ General parameters ``inmodel [string]`` Input model XML file. - + ``expcube [file]`` Input exposure cube file. @@ -80,10 +80,10 @@ General parameters ``caldb [string]`` Calibration database. - + ``irf [string]`` Instrument response function. - + ``(edisp = no) [boolean]`` Applies energy dispersion to response computation. @@ -115,23 +115,23 @@ Standard parameters ``(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 model 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctlike.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctmapcube.rst b/doc/source/users/reference_manual/ctmapcube.rst index 741b17b..0aa45ae 100644 --- a/doc/source/users/reference_manual/ctmapcube.rst +++ b/doc/source/users/reference_manual/ctmapcube.rst @@ -96,7 +96,7 @@ Standard parameters 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctmapcube.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctmodel.rst b/doc/source/users/reference_manual/ctmodel.rst index 5a786d3..1a1e94c 100644 --- a/doc/source/users/reference_manual/ctmodel.rst +++ b/doc/source/users/reference_manual/ctmodel.rst @@ -70,73 +70,73 @@ General parameters ``caldb [string]`` Calibration database. - + ``irf [string]`` Instrument response function. - + ``(edisp = no) [boolean]`` Apply energy dispersion to response computation. ``outcube [file]`` Output model cube file. - + ``ra [real]`` Right Ascension of pointing (J2000, in degrees). - + ``dec [real]`` Declination of pointing (J2000, in degrees). ``rad [real]`` Radius of field of view (in degrees). - + ``tmin [time]`` Start time (UTC string, JD, MJD or MET in seconds). - + ``tmax [time]`` Stop time (UTC string, JD, MJD or MET in seconds). - + ``(deadc = 0.95) [real]`` Average deadtime correction factor. ``(ebinalg = LOG) [string]`` Algorithm for defining energy bins. - + ``emin [real]`` Lower energy value for first energy bin (in TeV). - + ``emax [real]`` Upper energy value for last energy bin (in TeV). - + ``enumbins [integer]`` Number of energy bins. - + ``(ebinfile = NONE) [file]`` Name of the file containing the energy bin definition. ``(usepnt = no) [boolean]`` Use pointing instead of xref/yref parameters? - + ``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 [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [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). - + Standard parameters ------------------- @@ -147,23 +147,23 @@ Standard parameters ``(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 model cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctmodel.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctobssim.rst b/doc/source/users/reference_manual/ctobssim.rst index 43d2517..2d3f690 100644 --- a/doc/source/users/reference_manual/ctobssim.rst +++ b/doc/source/users/reference_manual/ctobssim.rst @@ -49,19 +49,19 @@ General parameters ``inmodel [file]`` Input model XML file. - + ``caldb [string]`` Calibration database. - + ``irf [string]`` Instrumental response function. - + ``(edisp = no) [boolean]`` Apply energy dispersion? - + ``outevents [file]`` Output event list or observation definition XML file. - + ``(prefix = sim_events_) [string]`` Prefix for event list in observation definition XML file. @@ -73,28 +73,28 @@ General parameters parameter at the same value for repeatable simulations, or increment this value for subsequent runs if non-repeatable simulations are required. - + ``ra [real]`` Right Ascension of CTA pointing (J2000, in degrees). - + ``dec [real]`` Declination of CTA pointing (J2000, in degrees). - + ``rad [real]`` Radius of CTA field of view (simulation cone radius) (in degrees). - + ``tmin [time]`` Start time (UTC string, JD, MJD or MET in seconds). - + ``tmax [time]`` Stop time (UTC string, JD, MJD or MET in seconds). ``emin [real]`` Lower energy limit of simulated events (in TeV). - + ``emax [real]`` Upper energy limit of simulated events (in TeV). - + ``(deadc = 0.95) [real]`` Average deadtime correction factor. @@ -115,23 +115,23 @@ Standard parameters ``(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 existing files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctobssim.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctphase.rst b/doc/source/users/reference_manual/ctphase.rst index 6d712c3..7a2d73e 100644 --- a/doc/source/users/reference_manual/ctphase.rst +++ b/doc/source/users/reference_manual/ctphase.rst @@ -23,13 +23,13 @@ General parameters ``inobs [file]`` Input event list or observation definition XML file. - + ``outobs [file]`` Output event list or observation definition XML file. - + ``(prefix = "phased_") [string]`` Prefix for output event lists in observation definition XML file. - + ``inmodel [string]`` Input model definition XML file. If ``NONE`` is specified the phase computation will be based on the ``mjd``, ``phase``, ``f0``, ``f1``, and ``f2`` @@ -64,23 +64,23 @@ Standard parameters ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctphase.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctprob.rst b/doc/source/users/reference_manual/ctprob.rst index 67c0455..18491b8 100644 --- a/doc/source/users/reference_manual/ctprob.rst +++ b/doc/source/users/reference_manual/ctprob.rst @@ -22,22 +22,22 @@ General parameters ``inobs [file]`` Input event list or observation definition XML file - + ``outobs [file]`` Output event list or observation definition XML file. - + ``(prefix = "prob_") [string]`` Prefix for output event lists in observation definition XML file. - + ``inmodel [string]`` Input model definition XML file. ``caldb [string]`` Calibration database. - + ``irf [string]`` Instrument response function. - + ``(edisp = no) [boolean]`` Applies energy dispersion to response computation. @@ -51,23 +51,23 @@ Standard parameters ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctprob.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctpsfcube.rst b/doc/source/users/reference_manual/ctpsfcube.rst index 59c3464..1fabd0e 100644 --- a/doc/source/users/reference_manual/ctpsfcube.rst +++ b/doc/source/users/reference_manual/ctpsfcube.rst @@ -56,53 +56,53 @@ General parameters ``ebinalg [string]`` Algorithm for defining energy bins. - + ``emin [real]`` Lower energy value for first energy bin (in TeV). - + ``emax [real]`` Upper energy value for last energy bin (in TeV). - + ``enumbins [integer]`` Number of energy bins. - + ``ebinfile [file]`` Name of the file containing the energy bin definition. - + ``(addbounds = no) [boolean]`` Add energies to the point spread function cube at the observation energy boundaries? ``(usepnt = no) [boolean]`` Use CTA pointing direction for cube centre instead of xref/yref parameters? - + ``nxpix [integer]`` Number of cube bins in Right Ascension or Galactic longitude. - + ``nypix [integer]`` Number of cube bins in Declination or Galactic latitude. - + ``binsz [real]`` Cube bin size (in degrees/pixel). - + ``coordsys [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [string]`` Projection method. ``xref [real]`` Right Ascension / Galactic longitude of cube centre (J2000, in degrees). - + ``yref [real]`` Declination / Galactic latitude of cube centre (J2000, in degrees). - + ``(amax = 0.3) [real]`` Upper bound of angular separation between true and measued photon direction (in degrees). ``(anumbins = 200) [integer]`` Number of angular separation bins. - + Standard parameters ------------------- @@ -110,23 +110,23 @@ Standard parameters ``(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 point spread function cube 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctpsfcube.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctselect.rst b/doc/source/users/reference_manual/ctselect.rst index 33dc41b..4b3748c 100644 --- a/doc/source/users/reference_manual/ctselect.rst +++ b/doc/source/users/reference_manual/ctselect.rst @@ -40,60 +40,60 @@ General parameters ``inobs [file]`` Input event list or observation definition XML file - + ``outobs [file]`` Output event list or observation definition XML file. - + ``(prefix = "selected_") [string]`` Prefix for output event lists in observation definition file. - + ``(usepnt = no) [boolean]`` Use pointing instead of RA/DEC parameters? - + ``ra [real]`` Right Ascension of acceptance cone (or ROI) centre (J2000, in degrees). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no ROI selection will be performed. - + ``dec [real]`` Declination of acceptance cone (or ROI) centre (J2000, in degrees). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no ROI selection will be performed. - + ``rad [real]`` Radius of acceptance cone (or ROI) centre (in degrees). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no ROI selection will be performed. - + ``tmin [time]`` Start time (UTC string, JD, MJD or time in seconds). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no time selection will be performed. - + ``tmax [time]`` Stop time (UTC string, JD, MJD or time in seconds). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no time selection will be performed. - + ``emin [real]`` Lower energy limit of events (in TeV). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no energy selection will be performed. - + ``emax [real]`` Upper energy limit of events (in TeV). If INDEF, NONE, UNDEF or UNDEFINED is passed as value, no energy selection will be performed. - + ``(phase = NONE) [string]`` String to apply a phase selection. The string must contain the boundaries of the phase interval to be selected separated be a colon. More than one interval can be specified at the same time. In this case intervals must be - separated by a comma. Examples of valid strings are: phase = "0.3:0.6", - phase = "0.3:0.6,0.8:0.9" or phase = "0.8:0.2". In the last case, events + separated by a comma. Examples of valid strings are: ``phase = 0.3:0.6``, + ``phase = 0.3:0.6,0.8:0.9`` or ``phase = 0.8:0.2``. In the last case, events with phases in the intervals [0.8,1.0] and [0.0,0.2] are selected. If NONE is passed as value, no phase selection will be performed. - + ``(expr = "") [string]`` Additional event selection expression (cfitsio syntax). @@ -110,23 +110,23 @@ Standard parameters ``(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 existing output files 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctlike.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctskymap.rst b/doc/source/users/reference_manual/ctskymap.rst index 1257aed..81f78da 100644 --- a/doc/source/users/reference_manual/ctskymap.rst +++ b/doc/source/users/reference_manual/ctskymap.rst @@ -43,37 +43,37 @@ General parameters ``outmap [file]`` Output sky map file. - + ``emin [real]`` Minimum energy in map (in TeV). - + ``emax [real]`` Maximum energy in map (in TeV). ``(usepnt = no) [boolean]`` Use pointing instead of xref/yref parameters? - + ``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 [string]`` Coordinate system (CEL - celestial, GAL - galactic). - + ``proj [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). - + Background subtraction configuration parameters ----------------------------------------------- @@ -103,24 +103,24 @@ Standard parameters ``(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 sky map 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctskymap.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/cttsmap.rst b/doc/source/users/reference_manual/cttsmap.rst index a3c656d..f7c787d 100644 --- a/doc/source/users/reference_manual/cttsmap.rst +++ b/doc/source/users/reference_manual/cttsmap.rst @@ -117,23 +117,23 @@ Standard parameters ``(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 TS map 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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = cttsmap.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/ctulimit.rst b/doc/source/users/reference_manual/ctulimit.rst index f2bb93e..01d1aa1 100644 --- a/doc/source/users/reference_manual/ctulimit.rst +++ b/doc/source/users/reference_manual/ctulimit.rst @@ -97,24 +97,24 @@ Standard parameters ``(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"). + Mode of automatic parameters (default is ``ql``, i.e. "query and learn"). ``(logfile = ctulimit.log) [string]`` Name of log file. diff --git a/doc/source/users/reference_manual/index.rst b/doc/source/users/reference_manual/index.rst index 8cf998e..1685791 100644 --- a/doc/source/users/reference_manual/index.rst +++ b/doc/source/users/reference_manual/index.rst @@ -63,8 +63,8 @@ cscripts csspec --- Computes spectral points cssrcdetect --- Detects sources in sky map cstsdist --- Generates Test Statistic distribution - cstsmapsplit --- Creates commands to split the Test Statistic map computations cstsmapmerge --- Merges slices from Test Statistic map computations + cstsmapsplit --- Creates commands to split the Test Statistic map computations csviscube --- Computes visibility cube diff --git a/doc/source/users/reference_manual/usage.rst b/doc/source/users/reference_manual/usage.rst index cb32547..80597e0 100644 --- a/doc/source/users/reference_manual/usage.rst +++ b/doc/source/users/reference_manual/usage.rst @@ -1,7 +1,10 @@ -Description of ctools parameters in the reference manual -===================================== +.. _sec_usage: -For a generic introduction to ctools and user parameters see `here <../user_manual/introduction.html>`__. +Description of ctools parameters in the :ref:`reference` +======================================================== + +For a generic introduction to ctools and user parameters see +`here <../user_manual/introduction.html>`__. Automatic parameters -------------------- @@ -27,18 +30,18 @@ Examples ``infile [file]`` Describes an automatic (queried) file-type parameter with no default value. - + ``irf = South_50h [string]`` Describes an automatic (queried) string-type parameter with two value options. - + ``(plot = yes) [boolean]`` Describes a hidden bool-type parameter named plot, whose default value is yes (true). - + .. note:: - You can set hidden parameters at runtime by specifying them explicitly on - the command line; for example: + You can set hidden parameters at runtime by specifying them explicitly on + the command line; for example: - ``ctobssim start_time=900`` + ``ctobssim start_time=900`` diff --git a/doc/source/users/tutorials/1dc/getting_tools.rst b/doc/source/users/tutorials/1dc/getting_tools.rst index 47aa64d..1bf921a 100644 --- a/doc/source/users/tutorials/1dc/getting_tools.rst +++ b/doc/source/users/tutorials/1dc/getting_tools.rst @@ -24,7 +24,7 @@ After downloading, configure GammaLib and ctools as follows: $ export CTOOLS=/usr/local/gamma $ source $CTOOLS/bin/ctools-init.sh -Have a look at :ref:`getting the ctools ` if you need more +Have a look at :ref:`getting the ctools ` if you need more information about the installation and configuration process. .. note:: diff --git a/doc/source/users/tutorials/beyond/beyond_residual_spectrum.rst b/doc/source/users/tutorials/beyond/beyond_residual_spectrum.rst index 5548e9c..001b3cd 100644 --- a/doc/source/users/tutorials/beyond/beyond_residual_spectrum.rst +++ b/doc/source/users/tutorials/beyond/beyond_residual_spectrum.rst @@ -1,7 +1,7 @@ .. _sec_residual_spectrum: Generating a residual spectrum -~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the previous tutorial you have used the :ref:`csresmap` script to inspect the spatial residuals. You can also inspect the spectral diff --git a/doc/source/users/user_manual/introduction.rst b/doc/source/users/user_manual/introduction.rst index a5b295f..1c55081 100644 --- a/doc/source/users/user_manual/introduction.rst +++ b/doc/source/users/user_manual/introduction.rst @@ -13,7 +13,7 @@ And you should read the :ref:`sec_develop` section if you would like to contribute to the ctools developments. Running ctools ---------------- +-------------- ctools comprises a set of ftools-like binary executables, written in C++, with a command-line interface allowing for interactive @@ -22,74 +22,71 @@ type the name of the ctool: .. code-block:: bash - $ ctobssim - RA of pointing (degrees) (0-360) [83.63] + $ ctobssim + RA of pointing (degrees) (0-360) [83.63] The ctool will query all user parameters and execute. User parameters can also be specified as arguments separated by a whitespace to the ctool: .. code-block:: bash - $ ctobssim ra=83.63 dec=22.01 rad=5.0 tmin=0 tmax=1800 emin=0.1 emax=100.0 caldb=prod2 irf=South_0.5h \ - inmodel=$CTOOLS/share/models/crab.xml outevents=events.fits + $ ctobssim ra=83.63 dec=22.01 rad=5.0 tmin=0 tmax=1800 emin=0.1 emax=100.0 caldb=prod2 irf=South_0.5h \ + inmodel=$CTOOLS/share/models/crab.xml outevents=events.fits If you need help about the usage of a ctool or a cscript, type the name of the ctool or cscript followed by the ``--help`` option: .. code-block:: bash - $ ctobssim --help + $ ctobssim --help ctools includes also a Python module that declares every ctool as a Python class. The following example illustrates the usage: -.. code-block:: bash +.. code-block:: python - $ python - >>> import ctools - >>> sim = ctools.ctobssim() - >>> sim["ra"] = 83.63 - >>> sim["dec"] = 22.01 - >>> sim.execute() - Radius of FOV (degrees) (0-180) [5.0] + $ python + >>> import ctools + >>> sim = ctools.ctobssim() + >>> sim["ra"] = 83.63 + >>> sim["dec"] = 22.01 + >>> sim.execute() + Radius of FOV (degrees) (0-180) [5.0] ctools comprise also cscripts, which are Python scripts that have the same user interface as the ctools binaries. cscripts can be started from the command line or used as Python classes, as illustrated below: -.. code-block:: bash +.. code-block:: python - $ python - >>> import cscripts - >>> pull = cscripts.cspull() + $ python + >>> import cscripts + >>> pull = cscripts.cspull() User parameters and parameter files ------------------------------ +----------------------------------- Each ctool and cscript has a defined list of user parameters. You can -find a complete description `here -<../reference_manual/reference.html>`_. +find a complete description `here <../reference_manual/reference.html>`_. -User parameters are stored in -par files. A ctools installation comprises a set of default par files -stored at ``$CTOOLS/syspfiles``. When you run a tool/script the latest -parameter values will be stored in a copy of the file at -``$HOME/pfiles`` (e.g., ``ctlike`` will save there a file called ``ctlike.par`` ). +User parameters are stored in par files. A ctools installation comprises a set +of default par files stored at ``$CTOOLS/syspfiles``. When you run a tool/script +the latest parameter values will be stored in a copy of the file at +``$HOME/pfiles`` (e.g., ``ctlike`` will save there a file called ``ctlike.par``). -When a tool/script is executed again, it will look for a par file -first in ``$HOME/pfiles``, and propose you to use the latest values -stored there. If no par file is found there, it will use the default -in ``$CTOOLS/syspfiles``. +When a tool/script is executed again, it will look for a par file first in +``$HOME/pfiles``, and propose you to use the latest values stored there. If no +par file is found there, it will use the default in ``$CTOOLS/syspfiles``. If you update your ctools installation you may get an error such as .. code-block:: bash - *** ERROR encounterted in the execution of ctlike. Run aborted ... - *** ERROR in GApplicationPars::load(GFilename&, - std::vector&): Invalid command line parameter - encountered (invalid parameter name "XX"): XX=2 + *** ERROR encounterted in the execution of ctlike. Run aborted ... + *** ERROR in GApplicationPars::load(GFilename&, + std::vector&): Invalid command line parameter + encountered (invalid parameter name "XX"): XX=2 -Remove the stale file ``ctlike.par`` from ``$HOME/pfiles`` and run -again to solve the issue. +Remove the stale file ``ctlike.par`` from ``$HOME/pfiles`` and run again to +solve the issue. diff --git a/test/test_csresspec.py b/test/test_csresspec.py index 6704db3..db1ff1b 100755 --- a/test/test_csresspec.py +++ b/test/test_csresspec.py @@ -77,7 +77,7 @@ class Test(test): ' outfile="csresspec_cmd1.fits"' + \ ' inmodel="' + self._model + '"' + \ ' caldb="' + self._caldb + '" irf="' + self._irf + '"' + \ - ' emin=0.1 emax=100.0 enumbins=20' + \ + ' emin=0.1 emax=100.0 enumbins=20 ebinalg="LOG"' + \ ' mask=no algorithm="SUB"' + \ ' logfile="csresspec_cmd1.log" chatter=4' @@ -93,7 +93,7 @@ class Test(test): ' outfile="csresspec_cmd2.fits"' + \ ' inmodel="' + self._model + '"' + \ ' caldb="' + self._caldb + '" irf="' + self._irf + '"' + \ - ' emin=0.1 emax=100.0 enumbins=20' + \ + ' emin=0.1 emax=100.0 enumbins=20 ebinalg="LOG"' + \ ' mask=no algorithm="SUBDIVSQRT"' + \ ' logfile="csresspec_cmd2.log" debug=yes chatter=2' @@ -119,6 +119,7 @@ class Test(test): resspec['inmodel'] = self._model resspec['caldb'] = self._caldb resspec['irf'] = self._irf + resspec['ebinalg'] = 'LOG' resspec['emin'] = 0.1 resspec['emax'] = 100.0 resspec['enumbins'] = 20 @@ -135,14 +136,15 @@ class Test(test): # Check result file self._check_result_file('csresspec_py1.fits', 20, 5) - # Set-up csresspec for event list - # with computation of individual model components + # Set-up csresspec for event list with computation of individual + # model components resspec = cscripts.csresspec() resspec['inobs'] = self._events resspec['outfile'] = 'csresspec_py2.fits' resspec['inmodel'] = self._model resspec['caldb'] = self._caldb resspec['irf'] = self._irf + resspec['ebinalg'] = 'LOG' resspec['emin'] = 0.1 resspec['emax'] = 100.0 resspec['enumbins'] = 20 @@ -181,8 +183,7 @@ class Test(test): # Check result file self._check_result_file('csresspec_py3.fits', 20, 5) - # Set-up csresspec for counts cube - # with source mask + # Set-up csresspec for counts cube with source mask resspec = cscripts.csresspec() resspec['inobs'] = self._cntcube resspec['modcube'] = 'NONE' -- libgit2 0.21.4