diff --git a/doc/source/reference_manual/ctbkgcube.rst b/doc/source/reference_manual/ctbkgcube.rst index c4b4188..a7d47be 100644 --- a/doc/source/reference_manual/ctbkgcube.rst +++ b/doc/source/reference_manual/ctbkgcube.rst @@ -54,7 +54,7 @@ General parameters Input model XML file. ``incube [file]`` - Counts cube for background cube definition. + Counts cube file to extract background cube definition. ``outcube [file]`` Output background cube file. diff --git a/doc/source/reference_manual/ctexpcube.rst b/doc/source/reference_manual/ctexpcube.rst index b66e56c..f85c3f6 100644 --- a/doc/source/reference_manual/ctexpcube.rst +++ b/doc/source/reference_manual/ctexpcube.rst @@ -45,7 +45,7 @@ General parameters Input event list or observation definition XML file. ``incube [file]`` - Counts cube for exposure cube definition. + Counts cube file to extract exposure cube definition. ``outcube [file]`` Output exposure cube file. diff --git a/doc/source/reference_manual/ctlike.rst b/doc/source/reference_manual/ctlike.rst index 0e0732f..79db24c 100644 --- a/doc/source/reference_manual/ctlike.rst +++ b/doc/source/reference_manual/ctlike.rst @@ -3,26 +3,54 @@ ctlike ====== -Performs binned and unbinned maximum likelihood analysis of CTA data. +Perform maximum likelihood model fitting. Synopsis -------- -Determines the flux, spectral index, position or extent of gamma-ray -sources using maximum likelihood model fitting of CTA data. The analysis -can be done in a binned or an unbinned formulation of the log-likelihood -function. For binned analysis, a counts cube produced by :doc:`ctbin` is -required. If several observations have been stacked into a single counts -cube, an exposure cube, a PSF cube and a background cube have to be -provided. For a single observation it is sufficient to specify the -instrument response function. For unbinned analysis, an event list -processed by :doc:`ctselect` is required. Based on files specified on -input, ctlike automatically selects between binned or unbinned analysis. -The tool can also be applied to lists of observations, specified in form -of an observation definition file in XML format. Events of each observation -are kept separate, and are associated to their appropriate instrument -response function. +This tool performs a maximum likelihood fitting of a model to unbinned or +binned data. All model parameters marked with the attribute ``free="1"`` +in the input model XML file will be adjusted to the value that maximises +the probability that the observed data have been drawn from the model. +The tool can mix the analysis of unbinned and binned data, and is also able +to perform a joint maximum likelihood analysis of data collected in +separate observations or with different instruments. + +ctlike will automatically switch between unbinned, binned and joint analysis +on basis of the file provided on input (parameter ``inobs``). Providing an +event list will lead to an unbinned analysis while providing a counts cube +will lead to a binned analysis. If several observations have been stacked +into a single counts cube, an exposure cube, a point spread function cube and +a background cube need also to be provided. ctlike will automatically prompt +for these parameters in case that a counts cube is given. Answering ``NONE`` +will ignore the exposure cube, point spread function cube and background cube +and handle the data as a single observation using the specified instrument +response function (parameters ``caldb`` and ``irf``). + +Multiple observations, including data collected with different instruments, +can be handled by specifying an observation definition file on input. Each of +the observations will be kept separatly and associated with its appropriate +instrument response functions, as opposed to a stacked analysis where average +response functions, computed using :doc:`ctexpcube`, :doc:`ctpsfcube` and :doc:`ctbkgcube`, +are used. If an observation definition file is provided, ctlike will use the +joint likelihood of all the observations for parameter optimisation. + +By default, ctlike will use the Poisson statistics for likelihood computation, +but for binned analysis also Gaussian statistics can be specified (parameter +``stat``). Optionally, a refit can be done after an initial fit (parameter ``refit``), +but normally this is not needed. For all model components that have the +``tscalc="1"`` attribute set, ctlike will also compute the Test Statistics +value that is a measure of the source significance. Optionally, the spatial +model parameters can be kept fixed during that computation (parameter +``fix_spat_for_ts``). + +ctlike generates an output model XML file that contains the values of the +best fitting model parameters. For all free parameters, an ``error`` attribute +is added that provides the statistical uncertainty in the parameter estimate. +If computation of the Test Statistics has been requested for a model component, +a ``ts`` attribute providing the Test Statistics value is added. The output +model can be used as an input model for other ctools. General parameters @@ -32,7 +60,7 @@ General parameters Input event list, counts cube or observation definition XML file. ``inmodel [string]`` - Source model input XML file. + Input model XML file. ``expcube [file]`` Exposure cube file (only needed for stacked analysis). @@ -49,16 +77,16 @@ General parameters ``irf [string]`` Instrument response function. +``(edisp = no) [boolean]`` + Applies energy dispersion to response computation. + ``outmodel [string]`` - Source model result XML file with values and uncertainties updated by + Output model XML file with values and uncertainties updated by the maximum likelihood fit. ``(stat = POISSON) [string]`` Fitting statistics (POISSON or GAUSSIAN; only affects binned analysis). -``(edisp = no) [boolean]`` - Applies energy dispersion to response computation. - ``(refit = no) [boolean]`` Perform refitting of solution after initial fit. diff --git a/doc/source/reference_manual/ctmodel.rst b/doc/source/reference_manual/ctmodel.rst index 199f2bd..2dabb3e 100644 --- a/doc/source/reference_manual/ctmodel.rst +++ b/doc/source/reference_manual/ctmodel.rst @@ -3,48 +3,67 @@ ctmodel ======= -Computes model counts cube. +Generate model cube. Synopsis -------- -This tool computes a model counts cube based on an XML model. The counts -cube is a 3-dimensional data cube spanned by Right Ascension or Galactic -longitude, Declination or Galactic latitude, and energy. +This tool generates a model cube based on an input model. A model cube is +a 3-dimensional cube providing the number of predicted counts for a model as +function of Right Ascension or Galactic longitude, Declination or Galactic +latitude, and energy. The energy binning may be either linear, logarithmic, +or custom defined using an input file. + +ctmodel requires on input either a counts cube, an event list or an observation +definition file. + +If a counts cube is provided, ctmodel will use the definition of this cube +(such as sky coordinates and projection, number of pixels, pixel scale, +energy binning) to compute a model cube. In case that the counts cube combines +multiple observations (i.e. for a so-called "stacked cube"), an exposure cube, +a point spread function cube and a background cube have to be provided +(otherwise you may just enter ``NONE`` when the names of these files are +queried). + +If an event list is provided, ctmodel will query for a counts cube to +extract the model cube definition (parameter ``incube``). If no counts cube +is provided (``incube=NONE``), ctmodel tools will query for cube definition +parameters. + +If an observation definition file is provided, ctmodel will query for a counts +cube to extract the model cube definition, unless the observation definition +file contains a single binned observation (in that case, the counts cube of +that observation will be used to extract the model cube definition). + +ctmodel generates a model cube FITS file comprising three extensions. The +primary extension contains a 3-dimensional image that contains the model +cube values. The next extension named ``EBOUNDS`` contains a binary table +that defines the energy boundaries of the background cube. The last extension +named ``GTI`` contains a binary table that defines the Good Time Intervals +that are covered by the model cube. General parameters ------------------ -``incube [file]`` - Input counts cube. If a filename is given the counts cube will be - used to define the dimensions of the model cube. The content of - the counts cube is not relevant. +``inobs [file]`` + Input event list, counts cube or observation definition XML file. ``inmodel [string]`` - Source model XML file. - -``outcube [file]`` - Output model counts cube. - -``(edisp = no) [boolean]`` - Apply energy dispersion to response computation. + Input model XML file. -``inobs [file]`` - Input event list, counts cube or observation definition XML file. - This information is needed to determine the observation information - (number of observations, duration, liftime, pointing, eventually - observation specific instrument response functions, etc.). +``incube [file]`` + Input counts cube file to extract model cube definition. ``expcube [file]`` - Exposure cube file (only needed for stacked analysis). + Input exposure cube file (only needed for stacked analysis). ``psfcube [file]`` - PSF cube file (only needed for stacked analysis). + Input PSF cube file (only needed for stacked analysis). ``bkgcube [file]`` - Background cube file (only needed for stacked analysis). + Input background cube file (only needed for stacked analysis). ``caldb [string]`` Calibration database. @@ -52,6 +71,12 @@ General parameters ``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). @@ -141,4 +166,7 @@ Standard parameters Related tools ------------- -None +:doc:`ctbin` +:doc:`ctexpcube` +:doc:`ctpsfcube` +:doc:`ctbkgcube` diff --git a/doc/source/reference_manual/ctpsfcube.rst b/doc/source/reference_manual/ctpsfcube.rst index 80ac18f..5cb62f2 100644 --- a/doc/source/reference_manual/ctpsfcube.rst +++ b/doc/source/reference_manual/ctpsfcube.rst @@ -45,7 +45,7 @@ General parameters Input event list or observation definition XML file. ``incube [file]`` - Counts cube for point spread function cube definition. + Counts cube file to extract point spread function cube definition. ``outcube [file]`` Output point spread function cube file.