Domenico Tiziani / ctools

Commit c6b0a9e2a8cf053cfe57618d510e2dad8db1b0d2

Authored by Jürgen Knödlseder
1 parent 34462914

Update reference manual for cscripts.

Inline Side-by-side
Showing 7 changed files with 144 additions and 57 deletions
doc/source/reference_manual/cslightcrv.rst
  View file @c6b0a9e
... ... @@ -9,12 +9,14 @@ Computes a lightcurve for a given source.
9 9 Synopsis
10 10 --------
11 11  
12   -Computes a lightcurve by performing a maximum likekihood fit in a series of
13   -time bins. The time bins can be either specified in an ASCII file, as an
14   -interval divided into equally sized time bins, or can be taken from the Good
15   -Time Intervals of the observation(s). The format of the ASCII file is one
16   -row per time bin, each specifying the start of stop value of the bin, separated
17   -by a whitespace. The times are given in Modified Julian Days (MJD).
  12 +This script computes a lightcurve by performing a maximum likelihood fit
  13 +using :doc:`ctlike` in a series of time bins. The time bins can be either
  14 +specified in an ASCII file, as an interval divided into equally sized time
  15 +bins, or can be taken from the Good Time Intervals of the observation(s).
  16 +The format of the ASCII file is one row per time bin, each specifying the
  17 +start of stop value of the bin, separated by a whitespace. The times are
  18 +given in Modified Julian Days (MJD).
  19 +
18 20 cslightcrv writes the fitted model parameters and their statistical errors
19 21 in a FITS file. In addition, it computes for each time bin the statistical
20 22 significance of the detection, expressed by the Test Statistics, and the
... ... @@ -28,7 +30,7 @@ General parameters
28 30 Input event list, counts cube or observation definition XML file.
29 31  
30 32 ``inmodel [file]``
31   - Input source model XML file.
  33 + Input model XML file.
32 34  
33 35 ``srcname [string]``
34 36 Name of the source in the source model XML file which should be used
... ... @@ -141,7 +143,7 @@ Standard parameters
141 143 Log filename.
142 144  
143 145  
144   -Related tools
145   --------------
  146 +Related tools or scripts
  147 +------------------------
146 148  
147   -None
  149 +:doc:`ctlike`
... ...
doc/source/reference_manual/csobsdef.rst
  View file @c6b0a9e
... ... @@ -10,9 +10,9 @@ Synopsis
10 10 --------
11 11  
12 12 The csobsdef script generates an observation definition file from
13   -a pointing list. The pointing list is a colon separated value ASCII
14   -file with header keywords in the first row followed by a list of
15   -pointings (one pointing per row). The following header keywords
  13 +a pointing list. The pointing list is a comma-separated value (CSV)
  14 +ASCII file with header keywords in the first row followed by a list
  15 +of pointings (one pointing per row). The following header keywords
16 16 are supported (case sensitive, column order irrelevant):
17 17  
18 18 * name - Observation name string
... ... @@ -32,7 +32,7 @@ are supported (case sensitive, column order irrelevant):
32 32 Only the pairs (ra,dec) or (lon,lat) are mandatory header keywords.
33 33 All other keywords are optional and can be specified when calling
34 34 csobsdef as user parameters. The only exception is the "duration"
35   -keyword that will automatically queried.
  35 +keyword that will automatically be queried.
36 36  
37 37 Here some usage examples:
38 38  
... ... @@ -54,7 +54,7 @@ General parameters
54 54 ------------------
55 55  
56 56 ``inpnt [file]``
57   - Pointing definition ASCII file in colon separated values format.
  57 + Pointing definition ASCII file in comma-separated value (CSV) format.
58 58  
59 59 ``outobs [file]``
60 60 Output Observation Definition XML file.
... ... @@ -109,7 +109,7 @@ Standard parameters
109 109 Log filename.
110 110  
111 111  
112   -Related tools
113   --------------
  112 +Related tools or scripts
  113 +------------------------
114 114  
115 115 None
... ...
doc/source/reference_manual/cspull.rst
  View file @c6b0a9e
... ... @@ -3,17 +3,33 @@
3 3 cspull
4 4 ======
5 5  
6   -Generates pull distribution for all model parameters.
  6 +Generates pull distribution for all free model parameters.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Generates pull distributions for all parameters in a model. The pull is
13   -defined by the fitted value minus the simulated true value, devided by
14   -the statistical uncertainty. For unbiased parameter estimates, the pull
15   -distribution should follow a Gaussian centred on 0 and a sigma parameter
16   -of 1.
  12 +This script generates pull distributions for all free model parameters.
  13 +The pull is defined as the fitted model parameter value minus the true
  14 +value, devided by the parameter error. cspull will perform ``ntrials``
  15 +statistically independent Monte Carlo simulations followed by maximum
  16 +likelihood model fitting to derive the pull distribution for each free
  17 +model parameter. If the model fit is unbiased and the parameters are
  18 +correct, the pull distribution should follow a Gaussian centred on 0
  19 +and with a sigma parameter of 1.
  20 +
  21 +cspull will generate an ASCII file in comma-separated value (CSV) format,
  22 +containing one row per pull. The first row is a header row providing the
  23 +column names. The following rows give the pull results, one row per pull.
  24 +This includes for each parameter the parameter value, error and pull. The
  25 +maximum likelihood value and the observed and the estimated number of counts
  26 +are also given.
  27 +
  28 +From the output file, pull distribution plots can be generated using for
  29 +example the ``show_pull_histogram.py`` script in the examples folder. The
  30 +script ``show_pull_evolution.py`` in the same folder shows the evolution
  31 +of the mean and standard deviation of the pull as function of the number
  32 +of trials. Both scripts require matplotlib for plotting.
17 33  
18 34  
19 35 General parameters
... ... @@ -23,8 +39,7 @@ General parameters
23 39 Event list, counts cube, or observation definition XML file.
24 40  
25 41 ``inmodel [file]``
26   - XML file that describes the astrophysical sources and the instrumental
27   - background.
  42 + Input model XML file.
28 43  
29 44 ``outfile [file]``
30 45 ASCII file containing the individual pull values.
... ... @@ -118,7 +133,8 @@ Standard parameters
118 133 Log filename.
119 134  
120 135  
121   -Related tools
122   --------------
  136 +Related tools or scripts
  137 +------------------------
123 138  
124   -None
  139 +:doc:`ctlike`
  140 +:doc:`cstsdist`
... ...
doc/source/reference_manual/csresmap.rst
  View file @c6b0a9e
... ... @@ -3,13 +3,26 @@
3 3 csresmap
4 4 ========
5 5  
6   -Generates residual counts map.
  6 +Generates residual map.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This scripts generates a residual counts map.
  12 +This scripts generates a residual map for a given model. It works for
  13 +event lists, counts cubes or observation definition files. For event
  14 +lists, parameters that define the spatial and spectral binning need to
  15 +be provided so that the script can bin the data internally. The model
  16 +is then convolved with the instrumental response function for that
  17 +binning and used for residual computation. Before residual computation,
  18 +the counts and model cubes are collapsed into maps by summing over all
  19 +energies. Three options exist then for residual computation:
  20 +
  21 +* the subtraction of the model from the counts (SUB)
  22 +* the subtraction and division by the model (SUBDIV)
  23 +* the subtraction and division by the square root of the model (SUBDIVSQRT)
  24 +
  25 +The residual map is written into a FITS file.
13 26  
14 27  
15 28 General parameters
... ... @@ -19,7 +32,7 @@ General parameters
19 32 Input event list, counts cube or observation definition XML file.
20 33  
21 34 ``inmodel [file]``
22   - Model XML file.
  35 + Input model XML file.
23 36  
24 37 ``outmap [file]``
25 38 Output residual counts map file.
... ... @@ -94,8 +107,11 @@ Standard parameters
94 107 ``(mode = ql) [string]``
95 108 Mode of automatic parameters (default is "ql", i.e. "query and learn").
96 109  
  110 +``(logfile = csresmap.log) [string]``
  111 + Log filename.
  112 +
97 113  
98   -Related tools
99   --------------
  114 +Related tools or scripts
  115 +------------------------
100 116  
101 117 None
... ...
doc/source/reference_manual/cssens.rst
  View file @c6b0a9e
... ... @@ -3,18 +3,40 @@
3 3 cssens
4 4 ======
5 5  
6   -Computes the CTA sensitivity for a number of energy bins.
  6 +Computes differential or integrated CTA sensitivity.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Computes the CTA sensitivity for a number of energy bins using :doc:`ctlike`.
13   -Crab spectra are fitted in narrow energy bins to simulated data, and the
14   -flux level is determined that leads to a particular significance. The
15   -significance is estimated using the Test Statistic value. The simplified
16   -assumption is made that the significance (in Gaussian sigma) is the square
17   -root of the Test Statistic.
  12 +This script computes the differential or integrated CTA sensitivity using
  13 +maximum likelihood fitting of a test source. The differential sensitivity
  14 +is determined for a number of energy bins, the integral sensitivity is
  15 +determined for a number of energy thresholds. The test source is fitted to
  16 +simulated data using :doc:`ctlike` to determine it's detection significance
  17 +as a function of source flux. The source flux is then varied until the
  18 +source significance achieves a given level, specified by the (hidden)
  19 +significance parameter ``sigma``. To damp variations between individual
  20 +Monte Carlo simulations, a sliding average is applied in the significance
  21 +computation (controlled by hidden ``num_avg`` parameter).
  22 +
  23 +The significance is estimated using the Test Statistic value, defined as
  24 +twice the log-likelihood difference that is obtained when fitting the
  25 +simulated data with and without the test source. The simplified assumption
  26 +is made that the significance (in Gaussian sigma) is the square root of
  27 +the Test Statistic.
  28 +
  29 +cssens will generate an ASCII file in comma-separated value (CSV) format
  30 +containing the sensitivity as function of energy. The first row is a header
  31 +row providing the column names. The following rows provide the mean
  32 +logarithmic energy and the boundaries of the energy bin for which the
  33 +sensitivity was computed. They also provide the flux within the energy bin
  34 +in Crab units, in photons (ph/cm2/s) and in energy (ers/cm2/s). Finally,
  35 +the sensitivity is given as the test source spectrum evaluated at the mean
  36 +logarithmic energy multiplied by the energy squared (erg/cm2/s).
  37 +
  38 +The sensitivity can be displayed using the ``show_sensitivity.py`` script
  39 +in the example folder. Matplotlib is required to execute the script.
18 40  
19 41  
20 42 General parameters
... ... @@ -24,7 +46,7 @@ General parameters
24 46 Input event list, counts cube or observation definition XML file.
25 47  
26 48 ``inmodel [file]``
27   - Input source model XML file.
  49 + Input model XML file.
28 50  
29 51 ``srcname [string]``
30 52 Name of the source in the source model XML file which should be used
... ... @@ -110,7 +132,7 @@ Standard parameters
110 132 Log filename.
111 133  
112 134  
113   -Related tools
114   --------------
  135 +Related tools or scripts
  136 +------------------------
115 137  
116   -None
  138 +:doc:`ctlike`
... ...
doc/source/reference_manual/csspec.rst
  View file @c6b0a9e
... ... @@ -9,7 +9,20 @@ Computes spectrum for a given source.
9 9 Synopsis
10 10 --------
11 11  
12   -Computes spectral points for a given source.
  12 +This script computes the source spectrum by fitting a model in a given set
  13 +of energy bins. The model fit per energy bin is performed using :doc:`ctlike`
  14 +and the script provides the possibility to fix sources other than the
  15 +source of interest (hidden parameter ``fix_srcs``) or to fix the background
  16 +model component(s) (hidden parameter ``fix_bkg``). The script computes the
  17 +source flux and its uncertainty in each energy bin, as well as the significance
  18 +of the source detection. Optionally, it also computes an upper flux limit
  19 +that is particularily useful in case that the source is not significantly
  20 +detected within an energy bin (hidden parameter ``calc_ulim``).
  21 +
  22 +The script works on event lists only.
  23 +
  24 +On output, the script will provide a FITS file with the fitted source
  25 +spectrum.
13 26  
14 27  
15 28 General parameters
... ... @@ -19,7 +32,7 @@ General parameters
19 32 Input event list, counts cube or observation definition XML file.
20 33  
21 34 ``inmodel [file]``
22   - Input source model XML file.
  35 + Input model XML file.
23 36  
24 37 ``srcname [string]``
25 38 Name of the source in the source model XML file which should be used
... ... @@ -126,7 +139,7 @@ Standard parameters
126 139 Log filename.
127 140  
128 141  
129   -Related tools
130   --------------
  142 +Related tools or scripts
  143 +------------------------
131 144  
132   -None
  145 +:doc:`ctlike`
... ...
doc/source/reference_manual/cstsdist.rst
  View file @c6b0a9e
... ... @@ -3,14 +3,30 @@
3 3 cstsdist
4 4 ========
5 5  
6   -Generates the TS distribution for a particular model.
  6 +Generates the TS distribution for a given source.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Generates the Test Statistics (TS) distribution for a particular model
13   -based on Monte-Carlo simulations.
  12 +This script generates the Test Statistics (TS) distribution for a given
  13 +source by repeatedly computing the TS value for ``ntrials`` simulated data
  14 +sets. The Test Statistics is defined as twice the log-likelihood difference
  15 +that is obtained when fitting simulated data with and without a given
  16 +source model component.
  17 +
  18 +This script either performs an unbinned or a binned simulation, stacked
  19 +analysis is not yet supported.
  20 +
  21 +cstsdist will create an ASCII file in comma-separated value (CSV) format,
  22 +containing one row per TS computation. The first row is a header row providing
  23 +the column names. The following rows give the TS value, the log-likelihood
  24 +values of the fit with or without the source, the number of observed and
  25 +fitted events, as well as the values and errors for all fitted parameters.
  26 +
  27 +From the output file, TS distribution plots can be generated using for
  28 +example the ``show_ts_distribution.py`` script in the examples folder. The
  29 +script require matplotlib for plotting.
14 30  
15 31  
16 32 General parameters
... ... @@ -20,11 +36,11 @@ General parameters
20 36 Input event list, counts cube or observation definition XML file.
21 37  
22 38 ``inmodel [file]``
23   - Input source model XML file.
  39 + Input model XML file.
24 40  
25 41 ``srcname [string]``
26 42 Name of the source in the source model XML file which should be used
27   - for sensitivity computation.
  43 + for Test Statistics computation.
28 44  
29 45 ``outfile [file]``
30 46 ASCII file containing the TS distribution values.
... ... @@ -118,7 +134,9 @@ Standard parameters
118 134 Log filename.
119 135  
120 136  
121   -Related tools
122   --------------
  137 +Related tools or scripts
  138 +------------------------
  139 +
  140 +:doc:`ctlike`
  141 +:doc:`cspull`
123 142  
124   -None
... ...