GammaLib  1.7.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GObservations.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GObservations.hpp - Observation container class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2009-2019 by Juergen Knoedlseder *
5  * ----------------------------------------------------------------------- *
6  * *
7  * This program is free software: you can redistribute it and/or modify *
8  * it under the terms of the GNU General Public License as published by *
9  * the Free Software Foundation, either version 3 of the License, or *
10  * (at your option) any later version. *
11  * *
12  * This program is distributed in the hope that it will be useful, *
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
15  * GNU General Public License for more details. *
16  * *
17  * You should have received a copy of the GNU General Public License *
18  * along with this program. If not, see <http://www.gnu.org/licenses/>. *
19  * *
20  ***************************************************************************/
21 /**
22  * @file GObservations.hpp
23  * @brief Observations container class interface definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GOBSERVATIONS_HPP
28 #define GOBSERVATIONS_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <string>
32 #include <vector>
33 #include "GContainer.hpp"
34 #include "GObservation.hpp"
35 #include "GOptimizerFunction.hpp"
36 #include "GModels.hpp"
37 
38 /* __ Forward declarations _______________________________________________ */
39 class GFilename;
40 class GOptimizer;
41 
42 
43 /***********************************************************************//**
44  * @class GObservations
45  *
46  * @brief Observation container class
47  *
48  * This is the main user interface class that provides high-level access to
49  * gamma-ray observations and manages their scientific analysis. For a given
50  * instruments, the identifiers of all observations in the container have to
51  * be unique, i.e. every identifier can occur only once. This allows for
52  * accessing the observations by instrument and by identifier.
53  *
54  * GObservations holds a list of pointers to GObservation objects which
55  * implement gamma-ray observations. The class derives from the abstract
56  * container interface class GContainer, and provides methods to manage the
57  * list of observations.
58  * The append() appends an observation to the container, the insert() method
59  * inserts an observation at a specific position in the list (though the
60  * order of the observations in the list is not relevant for the scientific
61  * analysis).
62  * The remove() method removes a specific observation from the list and the
63  * extend() method extends the list of observations by appending another
64  * list of observations to it.
65  * The size() method provides the number of observations in the list.
66  *
67  * The operator[] provides access to an observation in the list by index,
68  * returning a reference to the observation. The operator does not perform
69  * index range checking. If range checking is required, use the at() method.
70  *
71  * The observation information may be stored into a XML file. The save()
72  * method saves all information into a XML file while the load() method
73  * loads the information into the list. Alternatively, a XML file
74  * constructor can be used to construct an instance of GObservations by
75  * loading observation information from a XML file. In addition, the
76  * read() and write() method handle the reading and writing of observation
77  * information from and into a XML object of type GXml.
78  *
79  * The class also holds a list of models that is implemented by the GModels
80  * class. The models() method allows setting and retrieving the list of
81  * models, as well as loading of models from an XML file.
82  *
83  * Based on the list of models, the optimize() method will optimize all
84  * model parameters that are marked as free in the list of models. The
85  * npred() method returns the total number of events that are predicted
86  * by all models after optimization.
87  *
88  * GObservations also provides an optimizer class that is derived from
89  * the abstract GOptimizerFunction base class. The GObservations::optimizer
90  * class is the object that is used for model parameter optimization.
91  ***************************************************************************/
92 class GObservations : public GContainer {
93 
94 public:
95  // Constructors and destructors
96  GObservations(void);
97  GObservations(const GObservations& obs);
98  explicit GObservations(const GFilename& filename);
99  virtual ~GObservations(void);
100 
101  // Operators
103  GObservation* operator[](const int& index);
104  const GObservation* operator[](const int& index) const;
105 
106  // Methods
107  void clear(void);
108  GObservations* clone(void) const;
109  std::string classname(void) const;
110  GObservation* at(const int& index);
111  const GObservation* at(const int& index) const;
112  int size(void) const;
113  bool is_empty(void) const;
114  GObservation* set(const int& index, const GObservation& obs);
115  GObservation* append(const GObservation& obs);
116  GObservation* insert(const int& index, const GObservation& obs);
117  void remove(const int& index);
118  void reserve(const int& num);
119  void extend(const GObservations& obs);
120  bool contains(const std::string& instrument,
121  const std::string& id) const;
122  void load(const GFilename& filename);
123  void save(const GFilename& filename) const;
124  void read(const GXml& xml);
125  void write(GXml& xml) const;
126  void models(const GModels& models);
127  void models(const GFilename& filename);
128  const GModels& models(void) const;
129  void optimize(GOptimizer& opt);
130  void errors(GOptimizer& opt);
131  void errors_hessian(void);
132  void eval(void);
133  double logL(void) const;
134  int nobserved(void) const;
135  double npred(void) const;
136  double npred(const std::string& name,
137  const std::string& instrument = "") const;
138  double npred(const GModel& model,
139  const std::string& instrument = "") const;
140  void remove_response_cache(void);
141  void remove_response_cache(const std::string& name);
142  std::string print(const GChatter& chatter = NORMAL) const;
143 
144  // Likelihood function
146  public:
147  // Constructors and destructors
148  likelihood(void);
150  likelihood(const likelihood& fct);
151  ~likelihood(void);
152 
153  // Operators
154  likelihood& operator=(const likelihood& fct);
155 
156  // Implemented pure virtual base class methods
157  virtual void eval(const GOptimizerPars& pars);
158  virtual double value(void) const;
159  virtual GVector* gradient(void);
160  virtual GMatrixSparse* curvature(void);
161 
162  // Other methods
163  void set(GObservations* obs);
164  double npred(void) const;
165  GMatrixSparse hessian(const GOptimizerPars& pars);
166  GMatrixSparse covariance(void) const;
167  void save(const GFilename& filename) const;
168 
169  protected:
170  // Protected methods
171  void init_members(void);
172  void copy_members(const likelihood& fct);
173  void free_members(void);
174  void save_csv(const GFilename& filename) const;
175  void save_fits(const GFilename& filename) const;
176  std::vector<std::string> covariance_names(void) const;
177 
178  // Protected data members
179  double m_value; //!< Function value
180  double m_npred; //!< Total number of predicted events
181  GVector* m_gradient; //!< Pointer to gradient vector
182  GMatrixSparse* m_curvature; //!< Pointer to curvature matrix
183  GObservations* m_this; //!< Pointer to GObservations object
184  };
185 
186  // Optimizer function access method
187  const GObservations::likelihood& function(void) const;
188 
189 protected:
190  // Protected methods
191  void init_members(void);
192  void copy_members(const GObservations& obs);
193  void free_members(void);
194  int get_index(const std::string& instrument,
195  const std::string& id) const;
196 
197  // Protected members
198  std::vector<GObservation*> m_obs; //!< List of observations
199  GModels m_models; //!< List of models
200  GObservations::likelihood m_fct; //!< Optimizer function
201 };
202 
203 
204 /***********************************************************************//**
205  * @brief Return class name
206  *
207  * @return String containing the class name ("GObservations").
208  ***************************************************************************/
209 inline
210 std::string GObservations::classname(void) const
211 {
212  return ("GObservations");
213 }
214 
215 
216 /***********************************************************************//**
217  * @brief Return pointer to observation
218  *
219  * @param[in] index Observation index [0,...,size()-1].
220  * @return Observation.
221  *
222  * Returns a pointer to the observation with specified @p index.
223  ***************************************************************************/
224 inline
226 {
227  return m_obs[index];
228 }
229 
230 
231 /***********************************************************************//**
232  * @brief Return pointer to observation (const version)
233  *
234  * @param[in] index Observation index [0,...,size()-1].
235  *
236  * Returns a const pointer to the observation with specified @p index.
237  ***************************************************************************/
238 inline
239 const GObservation* GObservations::operator[](const int& index) const
240 {
241  return m_obs[index];
242 }
243 
244 
245 /***********************************************************************//**
246  * @brief Return number of observations in container
247  *
248  * @return Number of observations in container.
249  *
250  * Returns the number of observations in the observation container.
251  ***************************************************************************/
252 inline
253 int GObservations::size(void) const
254 {
255  return (int)m_obs.size();
256 }
257 
258 
259 /***********************************************************************//**
260  * @brief Signals if there are no observations in container
261  *
262  * @return True if container is empty, false otherwise.
263  *
264  * Signals if the observation container does not contain any observation.
265  ***************************************************************************/
266 inline
267 bool GObservations::is_empty(void) const
268 {
269  return (m_obs.empty());
270 }
271 
272 
273 /***********************************************************************//**
274  * @brief Reserves space for observations in container
275  *
276  * @param[in] num Number of observations.
277  *
278  * Reserves space for @p num observations in the container.
279  ***************************************************************************/
280 inline
281 void GObservations::reserve(const int& num)
282 {
283  m_obs.reserve(num);
284  return;
285 }
286 
287 
288 /***********************************************************************//**
289  * @brief Set model container
290  *
291  * @param[in] models Model container.
292  *
293  * Sets the model container for the observations.
294  ***************************************************************************/
295 inline
296 void GObservations::models(const GModels& models)
297 {
298  m_models = models;
299  return;
300 }
301 
302 
303 /***********************************************************************//**
304  * @brief Return model container
305  *
306  * @return Model container.
307  *
308  * Returns the model container of the observations.
309  ***************************************************************************/
310 inline
311 const GModels& GObservations::models(void) const
312 {
313  return m_models;
314 }
315 
316 
317 /***********************************************************************//**
318  * @brief Return log-likelihood of models
319  *
320  * @return Log-likelihood of models.
321  *
322  * Returns the log-likelihood of models. This value if computed following a
323  * call of the optimize() or eval() methods. If optimize() or eval() have
324  * never been called, the method returns 0.
325  ***************************************************************************/
326 inline
327 double GObservations::logL(void) const
328 {
329  return (m_fct.value());
330 }
331 
332 
333 /***********************************************************************//**
334  * @brief Return total number of predicted events in models
335  *
336  * @return Total number of predicted events in models.
337  *
338  * Returns the total number of events that is predicted by the models. This
339  * number if computed following a call of the optimize() or eval() methods.
340  * If optimize() or eval() have never been called, the method returns 0.
341  ***************************************************************************/
342 inline
343 double GObservations::npred(void) const
344 {
345  return (m_fct.npred());
346 }
347 
348 
349 /***********************************************************************//**
350  * @brief Return likelihood function
351  *
352  * @return Reference to likelihood function.
353  *
354  * Returns a reference to the likelihood function.
355  ***************************************************************************/
356 inline
358 {
359  return m_fct;
360 }
361 
362 
363 /***********************************************************************//**
364  * @brief Return log-likelihood value of optimizer function
365  *
366  * @return Log-likelihood value of optimizer function.
367  *
368  * Returns the log-likelihood value of optimizer function.
369  ***************************************************************************/
370 inline
372 {
373  return m_value;
374 }
375 
376 
377 /***********************************************************************//**
378  * @brief Return total number of predicted events
379  *
380  * @return Total number of predicted events.
381  *
382  * Returns the total number of events that is predicted by the models after
383  * they have been fitted to the data.
384  ***************************************************************************/
385 inline
387 {
388  return m_npred;
389 }
390 
391 
392 /***********************************************************************//**
393  * @brief Return pointer to gradient vector
394  *
395  * @return Pointer to gradient vector.
396  *
397  * Returns a pointer to the parameter gradient vector.
398  ***************************************************************************/
399 inline
401 {
402  return m_gradient;
403 }
404 
405 
406 /***********************************************************************//**
407  * @brief Return pointer to curvature matrix
408  *
409  * @return Pointer to curvature matrix.
410  *
411  * Returns a pointer to the parameter curvature matrix.
412  ***************************************************************************/
413 inline
415 {
416  return m_curvature;
417 }
418 
419 
420 /***********************************************************************//**
421  * @brief Set observation container
422  *
423  * @param[in] obs Pointer to observation container.
424  *
425  * Sets the pointer to the observation container for which the optimizer
426  * class should be used.
427  ***************************************************************************/
428 inline
430 {
431  m_this = obs;
432  return;
433 }
434 
435 #endif /* GOBSERVATIONS_HPP */
GObservations * m_this
Pointer to GObservations object.
Abstract model class.
Definition: GModel.hpp:97
GObservations * clone(void) const
Clone observations.
likelihood(void)
Void constructor.
double m_value
Function value.
Optimizer function abstract base class.
Sparse matrix class interface definition.
void save_csv(const GFilename &filename) const
Save likelihood fit results into CSV file.
Model container class definition.
virtual double value(void) const
Return log-likelihood value of optimizer function.
void save(const GFilename &filename) const
Save observations into XML file.
Optimizer parameter container class.
void save(const GFilename &filename) const
Save likelihood fit results into a CSV or FITS file.
std::string classname(void) const
Return class name.
GVector * m_gradient
Pointer to gradient vector.
GMatrixSparse hessian(const GOptimizerPars &pars)
Compute Hessian matrix.
GObservation * append(const GObservation &obs)
Append observation to container.
GMatrixSparse * m_curvature
Pointer to curvature matrix.
bool contains(const std::string &instrument, const std::string &id) const
Signals if observation exists.
double m_npred
Total number of predicted events.
double logL(void) const
Return log-likelihood of models.
void errors(GOptimizer &opt)
Computes parameter errors using optimizer.
void save_fits(const GFilename &filename) const
Save likelihood fit results into FITS file.
void free_members(void)
Delete class members.
const GModels & models(void) const
Return model container.
virtual ~GObservations(void)
Destructor.
std::string print(const GChatter &chatter=NORMAL) const
Print observation list information.
GObservation * set(const int &index, const GObservation &obs)
Set observation in container.
void copy_members(const GObservations &obs)
Copy class members.
std::vector< GObservation * > m_obs
List of observations.
virtual GMatrixSparse * curvature(void)
Return pointer to curvature matrix.
Optimizer function abstract base class.
const GObservations::likelihood & function(void) const
Return likelihood function.
void errors_hessian(void)
Computes parameter errors using hessian matrix and optimizer.
void set(GObservations *obs)
Set observation container.
Model container class.
Definition: GModels.hpp:150
GObservations(void)
Void constructor.
bool is_empty(void) const
Signals if there are no observations in container.
GModels m_models
List of models.
XML class.
Definition: GXml.hpp:172
Filename class.
Definition: GFilename.hpp:62
GObservations & operator=(const GObservations &obs)
Assignment operator.
double npred(void) const
Return total number of predicted events in models.
int get_index(const std::string &instrument, const std::string &id) const
Return observation index by instrument and identifier.
void read(const GXml &xml)
Read observations from XML document.
std::vector< std::string > covariance_names(void) const
Return covariance matrix row and column names.
void init_members(void)
Initialise class members.
likelihood & operator=(const likelihood &fct)
Assignment operator.
Abstract optimizer abstract base class.
Definition: GOptimizer.hpp:54
double npred(void) const
Return total number of predicted events.
GChatter
Definition: GTypemaps.hpp:33
void optimize(GOptimizer &opt)
Optimize model parameters using optimizer.
Abstract observation base class.
int size(void) const
Return number of observations in container.
Abstract observation base class interface definition.
void eval(void)
Evaluate function.
Observation container class.
GObservation * insert(const int &index, const GObservation &obs)
Insert observation into container.
virtual void eval(const GOptimizerPars &pars)
Evaluate log-likelihood function.
int nobserved(void) const
Return total number of observed events.
void extend(const GObservations &obs)
Append observations from observation container.
GMatrixSparse covariance(void) const
Compute covariance matrix.
void write(GXml &xml) const
Write observations into XML document.
void copy_members(const likelihood &fct)
Copy class members.
GObservation * operator[](const int &index)
Return pointer to observation.
Definition of interface for container classes.
Vector class.
Definition: GVector.hpp:46
void load(const GFilename &filename)
Load observations from XML file.
void clear(void)
Clear observations.
void free_members(void)
Delete class members.
void remove_response_cache(void)
Remove response cache for all models.
GObservations::likelihood m_fct
Optimizer function.
void init_members(void)
Initialise class members.
GObservation * at(const int &index)
Return pointer to observation.
virtual GVector * gradient(void)
Return pointer to gradient vector.
Interface class for container classes.
Definition: GContainer.hpp:52
void reserve(const int &num)
Reserves space for observations in container.