Michael Mayer / ctools

Commit c68dc5b4452de07bed9d4f1a5afebdf5f8f672d7

Authored by Jürgen Knödlseder
1 parent c1b24c0f

Implement background model subtraction in ctskymap (#1882)

Inline Side-by-side
Showing 9 changed files with 232 additions and 52 deletions
ChangeLog
  View file @c68dc5b
1   -2016-11-23
  1 +2016-11-25
2 2  
3 3 * Version 1.2.0 released
4 4 ========================
5 5  
  6 + Add background subtraction to ctskymap tool (#1882)
6 7 Add csobsselect script (#1881)
7 8 Add csmodelselect script (#1879)
8 9 Add startindex parameter to ctobssim (#1878)
... ...
1 1 New Features and Important Changes in ctools 1.2.0
2 2  
3   -23 November 2016
  3 +25 November 2016
4 4  
5 5  
6 6 Introduction
... ... @@ -123,6 +123,11 @@ of the tool (#1835).
123 123 The ctskymap::map() method has been renamed to ctskymap::skymap() to avoid a
124 124 name conflict with Python (#1828).
125 125  
  126 +The tool now also supports subtraction of background models that can be enabled
  127 +using the "bkgsubtract" parameter. If this parameter is set to "IRF" the
  128 +background templates shipped with the Instrument Response Function will be
  129 +subtracted from the sky map (#1882).
  130 +
126 131  
127 132 ctmodel - CTA counts cube modelling
128 133 -----------------------------------
... ...
doc/source/users/reference_manual/ctskymap.rst
  View file @c68dc5b
... ... @@ -14,6 +14,12 @@ provided in an observation definition file. The tool will loop over all event
14 14 lists that are provided and fill all events into a single sky map. Only events
15 15 within an energy interval spanned by ``emin`` and ``emax`` are considered.
16 16  
  17 +Optionally, the tool will subtract a background model from the sky map. The
  18 +background subtraction method can be selected using the ``bkgsubtract``
  19 +parameter. By default, no background model is subtracted (method ``NONE``).
  20 +If ``IRF`` is selected, the background template that are shipped with the
  21 +Instrument Response Functions will be used for background subtraction.
  22 +
17 23 ctskymap generates a FITS file comprising a sky map as primary extension.
18 24  
19 25  
... ... @@ -21,47 +27,50 @@ General parameters
21 27 ------------------
22 28  
23 29 ``inobs [file]``
24   - Input event list or observation definition XML file.
  30 + Input event list or observation definition XML file
25 31  
26 32 ``outmap [file]``
27   - Output sky map file.
  33 + Output sky map file
28 34  
29 35 ``emin [real]``
30   - Minimum energy in map (in TeV).
  36 + Minimum energy in map (in TeV)
31 37  
32 38 ``emax [real]``
33   - Maximum energy in map (in TeV).
  39 + Maximum energy in map (in TeV)
34 40  
35 41 ``(usepnt = no) [boolean]``
36 42 Use pointing instead of xref/yref parameters?
37 43  
38 44 ``nxpix [integer]``
39   - Size of the Right Ascension / Galactic longitude axis (in pixels).
  45 + Size of the Right Ascension / Galactic longitude axis (in pixels)
40 46  
41 47 ``nypix [integer]``
42   - Size of the Declination / Galactic latitude axis (in pixels).
  48 + Size of the Declination / Galactic latitude axis (in pixels)
43 49  
44 50 ``binsz [real]``
45 51 Pixel size (in degrees/pixel).
46 52  
47 53 ``coordsys <CEL|GAL> [string]``
48   - Coordinate system (CEL - celestial, GAL - galactic).
  54 + Coordinate system (CEL - celestial, GAL - galactic)
49 55  
  56 +``proj <AIT|AZP|CAR|MER|STG|TAN> [string]``
  57 + Projection method
  58 +
50 59 ``xref [real]``
51   - Right Ascension / Galactic longitude of image centre (J2000, in degrees).
  60 + Right Ascension / Galactic longitude of image centre (J2000, in degrees)
52 61  
53 62 ``yref [real]``
54   - Declination / Galactic latitude of image centre (J2000, in degrees).
  63 + Declination / Galactic latitude of image centre (J2000, in degrees)
55 64  
56   -``proj <AIT|AZP|CAR|MER|STG|TAN> [string]``
57   - Projection method.
  65 +``bkgsubtract <NONE|IRF> [string]``
  66 + Background subtraction method
58 67  
59 68  
60 69 Standard parameters
61 70 -------------------
62 71  
63 72 ``(publish = no) [boolean]``
64   - Specifies whether the sky map should be published on VO Hub.
  73 + Specifies whether the sky map should be published on VO Hub
65 74  
66 75 ``(chatter = 2) [integer]``
67 76 Verbosity of the executable:
... ... @@ -76,16 +85,16 @@ Standard parameters
76 85 chatter = 4: detailed report about the task execution
77 86  
78 87 ``(clobber = yes) [boolean]``
79   - Specifies whether an existing output sky map file should be overwritten.
  88 + Specifies whether an existing output sky map file should be overwritten
80 89  
81 90 ``(debug = no) [boolean]``
82 91 Enables debug mode. In debug mode the executable will dump any log file output to the console.
83 92  
84 93 ``(mode = ql) [string]``
85   - Mode of automatic parameters (default is "ql", i.e. "query and learn").
  94 + Mode of automatic parameters (default is "ql", i.e. "query and learn")
86 95  
87 96 ``(logfile = ctskymap.log) [string]``
88   - Name of log file.
  97 + Name of log file
89 98  
90 99  
91 100 Related tools or scripts
... ...
doc/source/users/tutorials/1dc/first_skymap.png
View file @c68dc5b

330 KB | W: | H:

356 KB | W: | H:

  • 2-up
  • Swipe
  • Onion skin
doc/source/users/tutorials/1dc/first_skymap.rst
  View file @c68dc5b
... ... @@ -21,14 +21,15 @@ You do this with the :ref:`ctskymap` tool by typing:
21 21 Size of the Y axis in pixels [200] 250
22 22 Lower energy limit (TeV) [0.1]
23 23 Upper energy limit (TeV) [100.0]
  24 + Background subtraction method (NONE|IRF) [NONE]
24 25 Output skymap file [skymap.fits]
25 26  
26   -We generate here a sky map centred on the Galactic Centre in Galactic
  27 +We generated here a sky map centred on the Galactic Centre in Galactic
27 28 coordinates using a cartesian projection.
28 29 The sky map is 10° wide and 5° high, with an image scale of 0.02° per pixel.
29   -All events between 0.1 and 100 TeV have been collected in the skymap.
30   -The :ref:`ctskymap` tool writes the result into the FITS file ``skymap.fits``
31   -that will be created in the ``my_first_analysis`` folder.
  30 +All events between 0.1 and 100 TeV were collected in the skymap.
  31 +The :ref:`ctskymap` tool wrote the sky map into the FITS file ``skymap.fits``
  32 +that was created in the ``my_first_analysis`` folder.
32 33 The FITS file can be displayed using for example ds9 (see below):
33 34  
34 35 .. figure:: first_skymap.png
... ... @@ -37,4 +38,40 @@ The FITS file can be displayed using for example ds9 (see below):
37 38  
38 39 *Sky map of the events recorded during the Galactic Plane Survey around the Galactic Centre*
39 40  
40   -Bla
  41 +The sky map shows a wide-spread distribution of events with a number of sources
  42 +superimposed.
  43 +Most of the events are due to irreducable background that hampers the
  44 +recognition of the gamma-ray sources.
  45 +To describe the irreducable background in the CTA data, templates of the
  46 +background event distribution are shipped together with the
  47 +:ref:`Instrument Response Functions <glossary_irf>`.
  48 +These template can be used by :ref:`ctskymap` to subtract the background
  49 +contribution.
  50 +To enable the background subtraction you should re-run :ref:`ctskymap` with
  51 +the background subtraction method set to ``IRF`` as follows:
  52 +
  53 +.. code-block:: bash
  54 +
  55 + $ ctskymap
  56 + Input event list or observation definition XML file [events.fits] obs.xml
  57 + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 0.0
  58 + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 0.0
  59 + Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
  60 + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] GAL
  61 + Image scale (in degrees/pixel) [0.02]
  62 + Size of the X axis in pixels [200] 500
  63 + Size of the Y axis in pixels [200] 250
  64 + Lower energy limit (TeV) [0.1]
  65 + Upper energy limit (TeV) [100.0]
  66 + Background subtraction method (NONE|IRF) [NONE] IRF
  67 + Output skymap file [skymap.fits]
  68 +
  69 +The figure below shows the resulting sky map.
  70 +The irreducable background has been subtracted and the sources of gamma-ray
  71 +emission are now clearly descernable.
  72 +
  73 +.. figure:: first_skymap_bkgsubtract.png
  74 + :width: 600px
  75 + :align: center
  76 +
  77 + *Background subtracted sky map of the events recorded during the Galactic Plane Survey around the Galactic Centre*
... ...
doc/source/users/tutorials/1dc/first_skymap_bkgsubtract.png 0 → 100644
View file @c68dc5b

429 KB
src/ctskymap/ctskymap.cpp
  View file @c68dc5b
... ... @@ -35,6 +35,7 @@
35 35 /* __ Method name definitions ____________________________________________ */
36 36 #define G_INIT_MAP "ctskymap::init_map(GCTAObservation* obs)"
37 37 #define G_BIN_EVENTS "ctskymap::bin_events(GCTAObservation*)"
  38 +#define G_BKG_SUBTRACT_IRF "ctskymap::bkg_subtract_irf(GCTAObservation*)"
38 39  
39 40 /* __ Debug definitions __________________________________________________ */
40 41  
... ... @@ -231,7 +232,10 @@ void ctskymap::run(void)
231 232  
232 233 // Map events into sky map
233 234 map_events(obs);
234   -
  235 +
  236 + // Subtract background from sky map
  237 + bkg_subtract(obs);
  238 +
235 239 } // endfor: looped over observations
236 240  
237 241 // Optionally publish sky map
... ... @@ -324,10 +328,11 @@ void ctskymap::init_members(void)
324 328 {
325 329 // Initialise members
326 330 m_skymap.clear();
327   - m_emin = 0.0;
328   - m_emax = 0.0;
329   - m_publish = false;
330   - m_chatter = static_cast<GChatter>(2);
  331 + m_emin = 0.0;
  332 + m_emax = 0.0;
  333 + m_bkgsubtract = "NONE";
  334 + m_publish = false;
  335 + m_chatter = static_cast<GChatter>(2);
331 336  
332 337 // Return
333 338 return;
... ... @@ -342,11 +347,12 @@ void ctskymap::init_members(void)
342 347 void ctskymap::copy_members(const ctskymap& app)
343 348 {
344 349 // Copy attributes
345   - m_skymap = app.m_skymap;
346   - m_emin = app.m_emin;
347   - m_emax = app.m_emax;
348   - m_publish = app.m_publish;
349   - m_chatter = app.m_chatter;
  350 + m_skymap = app.m_skymap;
  351 + m_emin = app.m_emin;
  352 + m_emax = app.m_emax;
  353 + m_bkgsubtract = app.m_bkgsubtract;
  354 + m_publish = app.m_publish;
  355 + m_chatter = app.m_chatter;
350 356  
351 357 // Return
352 358 return;
... ... @@ -382,10 +388,11 @@ void ctskymap::get_parameters(void)
382 388 m_skymap = create_map(m_obs);
383 389  
384 390 // Get remaining parameters
385   - m_emin = (*this)["emin"].real();
386   - m_emax = (*this)["emax"].real();
387   - m_publish = (*this)["publish"].boolean();
388   - m_chatter = static_cast<GChatter>((*this)["chatter"].integer());
  391 + m_emin = (*this)["emin"].real();
  392 + m_emax = (*this)["emax"].real();
  393 + m_bkgsubtract = (*this)["bkgsubtract"].string();
  394 + m_publish = (*this)["publish"].boolean();
  395 + m_chatter = static_cast<GChatter>((*this)["chatter"].integer());
389 396  
390 397 // Read ahead parameters
391 398 if (read_ahead()) {
... ... @@ -407,16 +414,18 @@ void ctskymap::get_parameters(void)
407 414 *
408 415 * @exception GException::no_list
409 416 * No event list found in observation.
410   - * @exception GCTAException::no_pointing
411   - * No valid CTA pointing found.
412 417 *
413 418 * This method maps the events found in a CTA events list into a sky map.
414 419 ***************************************************************************/
415 420 void ctskymap::map_events(GCTAObservation* obs)
416 421 {
  422 + // Get non-const pointer on a CTA event list
  423 + GCTAEventList* events = dynamic_cast<GCTAEventList*>
  424 + (const_cast<GEvents*>(obs->events()));
  425 +
417 426 // Make sure that the observation holds a CTA event list. If this
418 427 // is not the case then throw an exception.
419   - if (dynamic_cast<const GCTAEventList*>(obs->events()) == NULL) {
  428 + if (events == NULL) {
420 429 throw GException::no_list(G_BIN_EVENTS);
421 430 }
422 431  
... ... @@ -433,8 +442,6 @@ void ctskymap::map_events(GCTAObservation* obs)
433 442 int num_in_map = 0;
434 443  
435 444 // Fill sky map
436   - GCTAEventList* events = static_cast<GCTAEventList*>
437   - (const_cast<GEvents*>(obs->events()));
438 445 for (int i = 0; i < events->size(); ++i) {
439 446  
440 447 // Get event
... ... @@ -477,3 +484,116 @@ void ctskymap::map_events(GCTAObservation* obs)
477 484 // Return
478 485 return;
479 486 }
  487 +
  488 +
  489 +/***********************************************************************//**
  490 + * @brief Subtract background events from skymap
  491 + *
  492 + * @param[in] obs CTA observation.
  493 + *
  494 + * Subtracts background events from the sky map using various methods. The
  495 + * background subtraction method is specified by the "bkgsubtract" parameter
  496 + * which can take the following values:
  497 + *
  498 + * NONE - No background subtraction
  499 + * IRF - Background subtraction based on IRF template
  500 + ***************************************************************************/
  501 +void ctskymap::bkg_subtract(GCTAObservation* obs)
  502 +{
  503 + // Dispatch to apporpriate background subtraction method
  504 + if (m_bkgsubtract == "IRF") {
  505 + bkg_subtract_irf(obs);
  506 + }
  507 +
  508 + // Return
  509 + return;
  510 +}
  511 +
  512 +
  513 +/***********************************************************************//**
  514 + * @brief Subtract background events based on IRF template from sky map
  515 + *
  516 + * @param[in] obs CTA observation.
  517 + *
  518 + * @exception GException::invalid_value
  519 + * No response information available for observation.
  520 + * No background template available in instrument response function.
  521 + *
  522 + * Subtracts background events from the sky map using the IRF template.
  523 + ***************************************************************************/
  524 +void ctskymap::bkg_subtract_irf(GCTAObservation* obs)
  525 +{
  526 + // Get IRF response
  527 + const GCTAResponseIrf* rsp = dynamic_cast<const GCTAResponseIrf*>(obs->response());
  528 +
  529 + // Throw an exception if observation has no instrument response function
  530 + if (rsp == NULL) {
  531 + std::string msg = "No response information available for "+
  532 + get_obs_header(obs)+" to compute IRF background. "
  533 + "Please specify response information or use "
  534 + "another background subtraction method.";
  535 + throw GException::invalid_value(G_BKG_SUBTRACT_IRF, msg);
  536 + }
  537 +
  538 + // Get IRF background template
  539 + const GCTABackground* bkg = rsp->background();
  540 +
  541 + // Throw an exception if observation has no IRF background template
  542 + if (bkg == NULL) {
  543 + std::string msg = "No IRF background template found in instrument "
  544 + "response function for "+
  545 + get_obs_header(obs)+". Please specify an instrument "
  546 + "response function containing a background template.";
  547 + throw GException::invalid_value(G_BKG_SUBTRACT_IRF, msg);
  548 + }
  549 +
  550 + // Setup energy range covered by data
  551 + GEnergy emin;
  552 + GEnergy emax;
  553 + GEbounds ebds;
  554 + emin.TeV(m_emin);
  555 + emax.TeV(m_emax);
  556 +
  557 + // Determine number of energy nodes, 20 per decade, at least 10 bins
  558 + int nebin = int((emax.log10TeV() - emin.log10TeV()) * 20.0);
  559 + if (nebin < 10) {
  560 + nebin = 10;
  561 + }
  562 +
  563 + // Setup energy nodes for computation
  564 + GEnergies energies(nebin, emin, emax); // More complicated nbins later
  565 +
  566 + // Loop over all sky map pixels
  567 + for (int i = 0; i < m_skymap.npix(); ++i) {
  568 +
  569 + // Get sky direction of pixel
  570 + GSkyDir skydir = m_skymap.inx2dir(i);
  571 +
  572 + // Convert sky direction in instrument direction
  573 + GCTAInstDir instdir = obs->pointing().instdir(skydir);
  574 +
  575 + // Compute background value for each energy node
  576 + std::vector<double> values(energies.size(), 0.0);
  577 + for (int k = 0; k < energies.size(); ++k) {
  578 + values[k] = (*bkg)(energies[k].log10TeV(), instdir.detx(),
  579 + instdir.dety());
  580 + }
  581 +
  582 + // Integrate background values according to Trapezoid rule
  583 + double value = 0;
  584 + for (int k = 1; k < energies.size(); ++k) {
  585 + value += 0.5 * (values[k] + values[k-1]) *
  586 + (energies[k].MeV() - energies[k-1].MeV());
  587 + }
  588 +
  589 + // Multiply background rate with livetime and solid angle
  590 + value *= obs->livetime() * m_skymap.solidangle(i);
  591 +
  592 + // Subtract background value from sky map
  593 + m_skymap(i,0) -= value;
  594 +
  595 + } // endfor: looped over sky map pixels
  596 +
  597 + // Return
  598 + return;
  599 +}
... ...
src/ctskymap/ctskymap.hpp
  View file @c68dc5b
... ... @@ -28,6 +28,7 @@
28 28 #define CTSKYMAP_HPP
29 29  
30 30 /* __ Includes ___________________________________________________________ */
  31 +#include <string>
31 32 #include "ctobservation.hpp"
32 33  
33 34 /* __Definitions _________________________________________________________ */
... ... @@ -69,13 +70,16 @@ protected:
69 70 void free_members(void);
70 71 void get_parameters(void);
71 72 void map_events(GCTAObservation* obs);
  73 + void bkg_subtract(GCTAObservation* obs);
  74 + void bkg_subtract_irf(GCTAObservation* obs);
72 75  
73 76 // User parameters
74   - GFilename m_outmap; //!< Output file name
75   - double m_emin; //!< Minimum energy (TeV)
76   - double m_emax; //!< Maximum energy (TeV)
77   - bool m_publish; //!< Publish sky map?
78   - GChatter m_chatter; //!< Chattiness
  77 + GFilename m_outmap; //!< Output file name
  78 + double m_emin; //!< Minimum energy (TeV)
  79 + double m_emax; //!< Maximum energy (TeV)
  80 + std::string m_bkgsubtract; //!< Background subtraction method
  81 + bool m_publish; //!< Publish sky map?
  82 + GChatter m_chatter; //!< Chattiness
79 83  
80 84 // Protected members
81 85 GSkyMap m_skymap; //!< Sky map
... ...
src/ctskymap/ctskymap.par
  View file @c68dc5b
... ... @@ -5,11 +5,10 @@
5 5 # ------------------------------------------------------------------------- #
6 6 # #
7 7 # File: ctskymap.par #
8   -# Version: 1.1.0 #
9 8 # #
10   -# Author: Jurgen Knodlseder #
11   -# knodlseder@cesr.fr #
12   -# IRAP #
  9 +# Author: Juergen Knoedlseder #
  10 +# jknodlseder@irap.omp.eu #
  11 +# IRAP, Toulouse, France #
13 12 # #
14 13 # Purpose: Parameter file for the ctskymap application #
15 14 # #
... ... @@ -33,10 +32,15 @@ usepnt, b, h, no,,, &quot;Use pointing instead of xref/yref parameters?&quot;
33 32 nxpix, i, a, 200,,, "Size of the X axis in pixels"
34 33 nypix, i, a, 200,,, "Size of the Y axis in pixels"
35 34 binsz, r, a, 0.02,,, "Image scale (in degrees/pixel)"
36   -coordsys, s, a, "CEL", CEL|GAL,,"Coordinate system (CEL - celestial, GAL - galactic)"
  35 +coordsys, s, a, CEL, CEL|GAL,,"Coordinate system (CEL - celestial, GAL - galactic)"
  36 +proj, s, a, CAR, AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
37 37 xref, r, a, 83.63,0,360, "First coordinate of image center in degrees (RA or galactic l)"
38 38 yref, r, a, 22.01,-90,90, "Second coordinate of image center in degrees (DEC or galactic b)"
39   -proj, s, a, "CAR", AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method"
  39 +
  40 +#
  41 +# Background subtraction parameters
  42 +#==================================
  43 +bkgsubtract, s, a, NONE, NONE|IRF,, "Background subtraction method"
40 44  
41 45 #
42 46 # Standard parameters
... ...