Add cslightcrv documentation and adapt slightly user parameters

Jürgen Knödlseder
1 parent 57b8ed27
Showing 5 changed files with 186 additions and 35 deletions
doc/source/reference_manual/cslightcrv.rst
doc/source/reference_manual/index.rst
doc/source/reference_manual/usage.rst
scripts/cslightcrv.py
test/test_cscripts.sh.in
+.. _cslightcrv:
+
+cslightcrv
+==========
+
+Computes a lightcurve for a given source.
+
+
+Synopsis
+--------
+
+Computes a lightcurve for a given source.
+
+
+General parameters
+------------------
+
+``(inobs = NONE) [file]``
+    Input event list, counts cube or observation definition XML file.
+
+``inmodel [file]``
+    Input source model XML file.
+
+``srcname [string]``
+    Name of the source in the source model XML file which should be used
+    for sensitivity computation.
+
+``outfile [file]``
+    Name of the source spectrum output file.
+
+``expcube [file]``
+    Exposure cube file (only needed for stacked analysis).
+
+``psfcube [file]``
+    PSF cube file (only needed for stacked analysis).
+
+``bkgcube [file]``
+    Background cube file (only needed for stacked analysis).
+
+``caldb [string]``
+    Calibration database.
+ 	 	 
+``irf [string]``
+    Instrumental response function.
+
+``tmin [real]``
+    Lightcurve start time (in MJD).
+
+``tmax [real]``
+    Lightcurve stop time (in MJD).
+
+``tbins [integer]``
+    Number of time bins.
+
+``(tbinalg = GTI) <FILE|LIN|GTI> [string]``
+    Algorithm for defining time bins.
+
+``tbinfile [file]``
+    File defining the time binning.
+
+``binned [boolean]``
+    Use binned analysis in each time bin.
+
+``enumbins [integer]``
+    Number of energy bins per light curve bin (0=unbinned).
+
+``emin [real]``
+    Lower energy limit of events (in TeV).
+ 	 	 
+``emax [real]``
+    Upper energy limit of events (in TeV).
+ 	 	 
+``coordsys <CEL|GAL> [string]``
+    Coordinate system (CEL - celestial, GAL - galactic).
+ 	 	 
+``proj <AIT|AZP|CAR|MER|MOL|STG|TAN> [string]``
+    Projection method.
+
+``xref [real]``
+    Right Ascension / Galactic longitude of image centre (J2000, in degrees).
+ 	 	 
+``yref [real]``
+    Declination / Galactic latitude of image centre (J2000, in degrees).
+
+``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).
+
+``(calc_ts = yes) [boolean]``
+    Compute TS value for each time bin?
+
+``(calc_ulim = yes) [boolean]``
+    Compute upper limit for each time bin?
+
+``(fix_srcs = yes) [boolean]``
+    Fix other sky model parameters?
+
+``(fix_bkg = no) [boolean]``
+    Fix background model parameters?
+
+
+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 should be overwritten.
+ 	 	 
+``(debug = no) [boolean]``
+    Enables debug mode. In debug mode the executable will dump any log file output to the console.
+ 	 	 
+``(mode = ql) [string]``
+    Mode of automatic parameters (default is "ql", i.e. "query and learn").
+
+``(logfile = cslightcrv.log) [filename]``
+    Log filename.
+
+
+Related tools
+-------------
+
+None
@@ -38,6 +38,7 @@ cscripts
  
    cscaldb --- Lists available instrument response functions <cscaldb>
    csobsdef --- Generates observation definition file <csobsdef>
+   cslightcrv --- Computes lightcurve <cslightcrv>
    cspull --- Generates pull distribution <cspull>
    cssens --- Computes CTA sensitivity <cssens>
    csspec --- Computes spectral points <csspec>
@@ -26,7 +26,7 @@ Examples
 ``infile [file]``
     Describes an automatic (queried) file-type parameter with no default value.
  
-``irf = kb_E_50h_v3 <kb_E_50h_v3|kb_H_50h_v3> [string]``
+``irf = South_50h <North_50h|South_50h> [string]``
     Describes an automatic (queried) string-type parameter with two value
     options.
  
@@ -39,4 +39,4 @@ Examples
   To set hidden parameters at runtime, specify them explicitly at 
   the command line; for example:
  
-  ``gtobssim start_time=900``
+  ``ctobssim start_time=900``
@@ -107,13 +107,15 @@ class cslightcrv(ctools.cscript):
             pars.append(gammalib.GApplicationPar("bkgcube","s","a","NONE","","","Background cube file (only needed for stacked analysis)"))
             pars.append(gammalib.GApplicationPar("caldb","s","a","prod2","","","Calibration database"))
             pars.append(gammalib.GApplicationPar("irf","s","a","South_50h","","","Instrument response function"))
-            pars.append(gammalib.GApplicationPar("tmin","r","a","51544.5","","days","Lightcurve Time start [MJD]"))
-            pars.append(gammalib.GApplicationPar("tmax","r","a","51544.6","","days","Lightcurve Time stop [MJD]"))
-            pars.append(gammalib.GApplicationPar("tbins","i","a","5","","","Number of time bins points"))
-            pars.append(gammalib.GApplicationPar("tbinalg","s", "a","GTI","FILE|LIN|GTI","", "Algorithm for defining energy bins"))
-            pars.append(gammalib.GApplicationPar("tbinfile","s", "a","tbins.fits","","", "File defining the time binning"))
-            pars.append(gammalib.GApplicationPar("binned","b","a","no","yes|no","","Use binned analysis in each energy bin"))
-            pars.append(gammalib.GApplicationPar("nebins","i","h","20","","","Number of energy bins per light curve point"))
+            pars.append(gammalib.GApplicationPar("tbinalg","s","h","GTI","FILE|LIN|GTI","", "Algorithm for defining time bins"))
+            pars.append(gammalib.GApplicationPar("tmin","r","a","51544.5","","days","Lightcurve start time [MJD]"))
+            pars.append(gammalib.GApplicationPar("tmax","r","a","51544.6","","days","Lightcurve stop time [MJD]"))
+            pars.append(gammalib.GApplicationPar("tbins","i","a","5","","","Number of time bins"))
+            pars.append(gammalib.GApplicationPar("tbinfile","f","a","tbins.fits","","", "File defining the time binning"))
+            #pars.append(gammalib.GApplicationPar("binned","b","a","no","yes|no","","Use binned analysis in each time bin"))
+            pars.append(gammalib.GApplicationPar("enumbins","i","a","0","","","Number of energy bins per light curve bin (0=unbinned)"))
+            pars.append(gammalib.GApplicationPar("emin","r","a","0.1","","","Lower energy limit of events (TeV)"))
+            pars.append(gammalib.GApplicationPar("emax","r","a","100.0","","","Upper energy limit of events (TeV)"))
             pars.append(gammalib.GApplicationPar("coordsys","s","a","CEL","CEL|GAL","","Coordinate System"))
             pars.append(gammalib.GApplicationPar("proj","s","a","CAR","AIT|AZP|CAR|MER|MOL|STG|TAN","","Projection method"))
             pars.append(gammalib.GApplicationPar("xref","r","a","83.63","0","360","First coordinate of image center in degrees (RA or galactic l)"))
@@ -121,12 +123,10 @@ class cslightcrv(ctools.cscript):
             pars.append(gammalib.GApplicationPar("nxpix","i","a","200","","","Size of the X axis in pixels"))
             pars.append(gammalib.GApplicationPar("nypix","i","a","200","","","Size of the Y axis in pixels"))
             pars.append(gammalib.GApplicationPar("binsz","r","a","0.02","","","Pixel size (deg/pixel)"))
-            pars.append(gammalib.GApplicationPar("emin","r","a","0.1","","","Lower energy limit for binned analysis (TeV)"))
-            pars.append(gammalib.GApplicationPar("emax","r","a","100.0","","","Upper energy limit for binned analysis (TeV)"))
-            pars.append(gammalib.GApplicationPar("calc_ts","b","h","yes","yes|no","","Compute TS value in each bin"))
-            pars.append(gammalib.GApplicationPar("calc_ulim","b","h","yes","yes|no","","Compute upper limit in each bin"))
-            pars.append(gammalib.GApplicationPar("fix_srcs","b","h","yes","yes|no","","Fix other skymodel parameters"))
-            pars.append(gammalib.GApplicationPar("fix_bkg","b","h","no","yes|no","","Fix background parameters"))
+            pars.append(gammalib.GApplicationPar("calc_ts","b","h","yes","yes|no","","Compute TS value for each bin?"))
+            pars.append(gammalib.GApplicationPar("calc_ulim","b","h","yes","yes|no","","Compute upper limit for each bin?"))
+            pars.append(gammalib.GApplicationPar("fix_srcs","b","h","yes","yes|no","","Fix other sky model parameters?"))
+            pars.append(gammalib.GApplicationPar("fix_bkg","b","h","no","yes|no","","Fix background model parameters?"))
             pars.append_standard()
             pars.append(gammalib.GApplicationPar("logfile","f","h","cslightcrv.log","","","Log filename"))
             pars.save(parfile)
@@ -190,22 +190,33 @@ class cslightcrv(ctools.cscript):
         # Get source name   
         self.m_srcname = self["srcname"].string()
  
-        # Get ebounds             
+        # Get time boundaries             
         self.create_tbounds()
  
+        # Unbinned or binned analysis?
+        self.m_ebins    = self["enumbins"].integer()
+        if self.m_ebins == 0:
+            self.m_binned = False
+        else:
+            self.m_binned = True
+
+        # Get energy range
+        self.m_emin = self["emin"].real()
+        self.m_emax = self["emax"].real()
+
         # Get binning flag
-        self.m_binned = self["binned"].boolean()
+        #self.m_binned = self["binned"].boolean()
         if self.m_binned:
+            self.m_coordsys = self["coordsys"].string()
+            self.m_proj     = self["proj"].string()
             self.m_xref     = self["xref"].real()
             self.m_yref     = self["yref"].real()
             self.m_nxpix    = self["nxpix"].integer()
             self.m_nypix    = self["nypix"].integer()
             self.m_binsz    = self["binsz"].real()
-            self.m_coordsys = self["coordsys"].string()
-            self.m_proj     = self["proj"].string()
-            self.m_ebins    = self["nebins"].integer()
-            self.m_emin     = self["emin"].real()
-            self.m_emax     = self["emax"].real()
+            #self.m_ebins    = self["enumbins"].integer()
+            #self.m_emin     = self["emin"].real()
+            #self.m_emax     = self["emax"].real()
  
         # Read other parameters
         self.m_outfile = self["outfile"].filename()
@@ -367,8 +378,8 @@ class cslightcrv(ctools.cscript):
  
             # Select events
             select = ctools.ctselect(self.obs)
-            select["emin"].value("UNDEFINED")    
-            select["emax"].value("UNDEFINED") 
+            select["emin"].real(self.m_emin)    
+            select["emax"].real(self.m_emax) 
             select["tmin"].real(tmin.convert(select.time_reference()))
             select["tmax"].real(tmax.convert(select.time_reference()))
             select["rad"].value("UNDEFINED")
@@ -257,14 +257,16 @@ chmod +x @abs_top_srcdir@/scripts/cslightcrv.py
 @abs_top_srcdir@/scripts/cslightcrv.py \
   inobs="data/crab_events.fits" \
   inmodel="data/crab.xml" \
+  srcname="Crab" \
   caldb="irf" \
   irf="cta_dummy_irf" \
-  tbins=3 \
+  tbinalg="LIN" \
   tmin=51544.5 \
   tmax=51544.53 \
-  srcname="Crab" \
-  tbinalg="LIN" \
-  binned=no \
+  tbins=3 \
+  enumbins=0 \
+  emin=0.1 \
+  emax=100.0 \
   outfile="lightcurve.fits" > cslightcrv.log
 $ECHO -n "."
 if [ -s "lightcurve.fits" ]
@@ -284,21 +286,20 @@ chmod +x @abs_top_srcdir@/scripts/cslightcrv.py
 @abs_top_srcdir@/scripts/cslightcrv.py \
   inobs="data/crab_events.fits" \
   inmodel="data/crab.xml" \
+  srcname="Crab" \
   caldb="irf" \
   irf="cta_dummy_irf" \
   tbinalg="GTI" \
-  srcname="Crab" \
+  enumbins=2 \
   emin=0.1 \
   emax=100.0 \
-  binned=yes \
-  nxpix=10 \
-  nypix=10 \
-  binsz=0.1 \
-  nebins=2 \
   coordsys="CEL" \
+  proj="CAR" \
   xref=83.63 \
   yref=22.01 \
-  proj="CAR" \
+  nxpix=10 \
+  nypix=10 \
+  binsz=0.1 \
   outfile="lightcurve.fits" > cslightcrv.log
 $ECHO -n "."
 if [ -s "lightcurve.fits" ]