GammaLib  2.0.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GObservation.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GObservation.hpp - Abstract observation base class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2008-2021 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 GObservation.hpp
23  * @brief Abstract observation base class interface definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GOBSERVATION_HPP
28 #define GOBSERVATION_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <string>
32 #include <vector>
33 #include "GBase.hpp"
34 #include "GEvents.hpp"
35 #include "GTime.hpp"
36 #include "GFunction.hpp"
37 #include "GModelPar.hpp"
38 
39 /* __ Forward declarations _______________________________________________ */
40 class GVector;
41 class GMatrixSparse;
42 class GModel;
43 class GModels;
44 class GResponse;
45 class GXmlElement;
46 
47 
48 /***********************************************************************//**
49  * @class GObservation
50  *
51  * @brief Abstract observation base class
52  *
53  * This class provides an abstract interface for an observation. The
54  * observation collects information about the instrument, holds the measured
55  * events, and provides information about the analysis definition.
56  *
57  * The response() method returns a pointer to the response function. The
58  * derived classes have to make sure that this method never returns NULL.
59  *
60  * The method model() returns the probability for an event to be measured
61  * with a given instrument direction, a given energy and at a given time,
62  * given a source model and an instrument pointing direction.
63  * The method npred() returns the total number of expected events within the
64  * analysis region for a given source model and a given instrument pointing
65  * direction.
66  * The methods are defined as virtual and can be overloaded by derived classes
67  * that implement instrument specific observations in order to optimize the
68  * execution speed for data analysis.
69  ***************************************************************************/
70 class GObservation : public GBase {
71 
72 public:
73  // Constructors and destructors
74  GObservation(void);
75  GObservation(const GObservation& obs);
76  virtual ~GObservation(void);
77 
78  // Operators
79  virtual GObservation& operator=(const GObservation& obs);
80 
81  // Pure virtual methods
82  virtual void clear(void) = 0;
83  virtual GObservation* clone(void) const = 0;
84  virtual std::string classname(void) const = 0;
85  virtual void response(const GResponse& rsp) = 0;
86  virtual const GResponse* response(void) const = 0;
87  virtual std::string instrument(void) const = 0;
88  virtual double ontime(void) const = 0;
89  virtual double livetime(void) const = 0;
90  virtual double deadc(const GTime& time = GTime()) const = 0;
91  virtual void read(const GXmlElement& xml) = 0;
92  virtual void write(GXmlElement& xml) const = 0;
93  virtual std::string print(const GChatter& chatter = NORMAL) const = 0;
94 
95  // Virtual methods
96  virtual GEvents* events(void);
97  virtual const GEvents* events(void) const;
98  virtual void events(const GEvents& events);
99  virtual double likelihood(const GModels& models,
100  GVector* gradients,
101  GMatrixSparse* curvature,
102  double* npred) const;
103  virtual double model(const GModels& models,
104  const GEvent& event,
105  GVector* gradients = NULL) const;
106  virtual GVector model(const GModels& models,
107  GMatrixSparse* gradients = NULL) const;
108  virtual int nobserved(void) const;
109  virtual double npred(const GModels& models,
110  GVector* gradients = NULL) const;
111  virtual double npred(const GModel& model) const;
112  virtual double model_grad(const GModel& model,
113  const GModelPar& par,
114  const GEvent& event) const;
115  virtual GVector model_grad(const GModel& model,
116  const GModelPar& par) const;
117  virtual double npred_grad(const GModel& model,
118  const GModelPar& par) const;
119  virtual void remove_response_cache(const std::string& name);
120  virtual const double& grad_step_size(void) const;
121 
122  // Implemented methods
123  bool has_events(void) const;
124  bool has_gradient(const GModel& model,
125  const GModelPar& par) const;
126  void name(const std::string& name);
127  void id(const std::string& id);
128  void statistic(const std::string& statistic);
129  const std::string& name(void) const;
130  const std::string& id(void) const;
131  const std::string& statistic(void) const;
132  void computed_gradient(const GModel& model,
133  const GModelPar& par) const;
134 
135 protected:
136  // Protected methods
137  void init_members(void);
138  void copy_members(const GObservation& obs);
139  void free_members(void);
140 
141  // Likelihood methods
142  virtual double likelihood_poisson_unbinned(const GModels& models,
143  GVector* gradients,
144  GMatrixSparse* curvature,
145  double* npred) const;
146  virtual double likelihood_poisson_binned(const GModels& models,
147  GVector* gradients,
148  GMatrixSparse* curvature,
149  double* npred) const;
150  virtual double likelihood_gaussian_binned(const GModels& models,
151  GVector* gradients,
152  GMatrixSparse* curvature,
153  double* npred) const;
154  virtual bool use_event_for_likelihood(const int& index) const;
155 
156  // Model gradient kernel classes
157  class model_func : public GFunction {
158  public:
159  model_func(const GObservation* parent,
160  const GModel* model,
161  GModelPar* par,
162  const GEvent* event) :
163  m_parent(parent),
164  m_model(model),
165  m_par(par),
166  m_event(event) { }
167  double eval(const double& x);
168  protected:
169  const GObservation* m_parent; //!< Observation
170  const GModel* m_model; //!< Model
171  GModelPar* m_par; //!< Model parameter
172  const GEvent* m_event; //!< Event
173  };
174 
175  // Npred methods
176  virtual double npred_spec(const GModel& model, const GTime& obsTime) const;
177 
178  // Npred kernel classes
179  class npred_kern : public GFunction {
180  public:
181  npred_kern(const GObservation* parent,
182  const GModel* model) :
183  m_parent(parent),
184  m_model(model) { }
185  double eval(const double& x);
186  protected:
187  const GObservation* m_parent; //!< Observation
188  const GModel* m_model; //!< Model
189  };
190 
191  class npred_spec_kern : public GFunction {
192  public:
194  const GModel* model,
195  const GTime* obsTime) :
196  m_parent(parent),
197  m_model(model),
198  m_time(obsTime) { }
199  double eval(const double& x);
200  protected:
201  const GObservation* m_parent; //!< Observation
202  const GModel* m_model; //!< Model
203  const GTime* m_time; //!< Time
204  };
205 
206  // Npred gradient kernel classes
207  class npred_func : public GFunction {
208  public:
209  npred_func(const GObservation* parent,
210  const GModel* model,
211  GModelPar* par) :
212  m_parent(parent),
213  m_model(model),
214  m_par(par) { }
215  double eval(const double& x);
216  protected:
217  const GObservation* m_parent; //!< Observation
218  const GModel* m_model; //!< Model
219  GModelPar* m_par; //!< Model parameter
220  };
221 
222  // Protected data area
223  std::string m_name; //!< Observation name
224  std::string m_id; //!< Observation identifier
225  std::string m_statistic; //!< Optimizer statistic
226  GEvents* m_events; //!< Pointer to event container
227  double m_grad_step_size; //!< Gradient step size
228 
229  // Stack of identifiers of parameters with gradients
230  mutable std::vector<std::string> m_pars_with_gradients;
231 };
232 
233 
234 /***********************************************************************//**
235  * @brief Signal if observation has events
236  *
237  * @return True if observation contains events.
238  ***************************************************************************/
239 inline
240 bool GObservation::has_events(void) const
241 {
242  return (m_events != NULL);
243 }
244 
245 
246 /***********************************************************************//**
247  * @brief Set observation name
248  *
249  * @param[in] name Observation name.
250  *
251  * Set name of the observation.
252  ***************************************************************************/
253 inline
254 void GObservation::name(const std::string& name)
255 {
256  m_name = name;
257  return;
258 }
259 
260 
261 /***********************************************************************//**
262  * @brief Set observation identifier
263  *
264  * @param[in] id Observation identifier.
265  *
266  * Set identifier of the observation.
267  ***************************************************************************/
268 inline
269 void GObservation::id(const std::string& id)
270 {
271  m_id = id;
272  return;
273 }
274 
275 
276 /***********************************************************************//**
277  * @brief Set optimizer statistic
278  *
279  * @param[in] statistic Optimizer statistic.
280  *
281  * Set optimizer statistic for the observation.
282  ***************************************************************************/
283 inline
284 void GObservation::statistic(const std::string& statistic)
285 {
287  return;
288 }
289 
290 
291 /***********************************************************************//**
292  * @brief Return observation name
293  *
294  * @return Observation name.
295  ***************************************************************************/
296 inline
297 const std::string& GObservation::name(void) const
298 {
299  return (m_name);
300 }
301 
302 
303 /***********************************************************************//**
304  * @brief Return observation identifier
305  *
306  * @return Observation identifier.
307  ***************************************************************************/
308 inline
309 const std::string& GObservation::id(void) const
310 {
311  return (m_id);
312 }
313 
314 
315 /***********************************************************************//**
316  * @brief Return optimizer statistic
317  *
318  * @return Optimizer statistic.
319  ***************************************************************************/
320 inline
321 const std::string& GObservation::statistic(void) const
322 {
323  return (m_statistic);
324 }
325 
326 
327 /***********************************************************************//**
328  * @brief Return gradient step size
329  *
330  * @return Gradient step size.
331  ***************************************************************************/
332 inline
333 const double& GObservation::grad_step_size(void) const
334 {
335  return (m_grad_step_size);
336 }
337 
338 #endif /* GOBSERVATION_HPP */
const std::string & statistic(void) const
Return optimizer statistic.
virtual double livetime(void) const =0
virtual std::string classname(void) const =0
Return class name.
Abstract model class.
Definition: GModel.hpp:100
double eval(const double &x)
Integration kernel for npred_spec() method.
virtual double likelihood_gaussian_binned(const GModels &models, GVector *gradients, GMatrixSparse *curvature, double *npred) const
Evaluate log-likelihood function for Gaussian statistic and binned analysis (version with working arr...
double m_grad_step_size
Gradient step size.
const GEvent * m_event
Event.
void computed_gradient(const GModel &model, const GModelPar &par) const
Signals that an analytical gradient was computed for a model parameter.
const GObservation * m_parent
Observation.
double eval(const double &x)
Integration kernel for npred() method.
virtual void read(const GXmlElement &xml)=0
virtual double ontime(void) const =0
std::string m_name
Observation name.
Sparse matrix class interface definition.
virtual std::string instrument(void) const =0
model_func(const GObservation *parent, const GModel *model, GModelPar *par, const GEvent *event)
virtual double npred_grad(const GModel &model, const GModelPar &par) const
Returns parameter gradient of Npred.
GEvents * m_events
Pointer to event container.
const GObservation * m_parent
Observation.
virtual double npred(const GModels &models, GVector *gradients=NULL) const
Return total number (and optionally gradients) of predicted counts for all models.
virtual double likelihood(const GModels &models, GVector *gradients, GMatrixSparse *curvature, double *npred) const
Compute likelihood function.
Abstract interface for the event classes.
Definition: GEvent.hpp:71
Definition of interface for all GammaLib classes.
XML element node class.
Definition: GXmlElement.hpp:48
const GModel * m_model
Model.
std::string m_id
Observation identifier.
virtual double model_grad(const GModel &model, const GModelPar &par, const GEvent &event) const
Returns parameter gradient of model for a given event.
Time class.
Definition: GTime.hpp:55
virtual void remove_response_cache(const std::string &name)
Response cache removal hook.
virtual double npred_spec(const GModel &model, const GTime &obsTime) const
Integrates spatially integrated Npred kernel spectrally.
virtual std::string print(const GChatter &chatter=NORMAL) const =0
Print content of object.
virtual int nobserved(void) const
Return total number of observed events.
void free_members(void)
Delete class members.
virtual ~GObservation(void)
Destructor.
Model parameter class interface definition.
Model parameter class.
Definition: GModelPar.hpp:87
Model container class.
Definition: GModels.hpp:152
const std::string & id(void) const
Return observation identifier.
Single parameter function abstract base class definition.
virtual double model(const GModels &models, const GEvent &event, GVector *gradients=NULL) const
Return model value and (optionally) gradients.
Interface class for all GammaLib classes.
Definition: GBase.hpp:52
virtual void clear(void)=0
Clear object.
GObservation(void)
Void constructor.
virtual bool use_event_for_likelihood(const int &index) const
Check whether bin should be used for likelihood analysis.
virtual double likelihood_poisson_unbinned(const GModels &models, GVector *gradients, GMatrixSparse *curvature, double *npred) const
Evaluate log-likelihood function for Poisson statistic and unbinned analysis (version with working ar...
const std::string & name(void) const
Return observation name.
double eval(const double &x)
Model function evaluation for gradient computation.
const GModel * m_model
Model.
const GObservation * m_parent
Observation.
virtual double deadc(const GTime &time=GTime()) const =0
virtual GObservation * clone(void) const =0
Clones object.
GChatter
Definition: GTypemaps.hpp:33
npred_spec_kern(const GObservation *parent, const GModel *model, const GTime *obsTime)
GModelPar * m_par
Model parameter.
GModelPar * m_par
Model parameter.
virtual double likelihood_poisson_binned(const GModels &models, GVector *gradients, GMatrixSparse *curvature, double *npred) const
Evaluate log-likelihood function for Poisson statistic and binned analysis (version with working arra...
void init_members(void)
Initialise class members.
Abstract observation base class.
virtual void write(GXmlElement &xml) const =0
const GModel * m_model
Model.
Abstract event container class.
Definition: GEvents.hpp:66
const GTime * m_time
Time.
Single parameter function abstract base class.
Definition: GFunction.hpp:44
std::string m_statistic
Optimizer statistic.
virtual GObservation & operator=(const GObservation &obs)
Assignment operator.
virtual GEvents * events(void)
Return events.
const GModel * m_model
Model.
std::vector< std::string > m_pars_with_gradients
bool has_events(void) const
Signal if observation has events.
npred_func(const GObservation *parent, const GModel *model, GModelPar *par)
double eval(const double &x)
Npred function evaluation for gradient computation.
Vector class.
Definition: GVector.hpp:46
void copy_members(const GObservation &obs)
Copy class members.
virtual const double & grad_step_size(void) const
Return gradient step size.
Abstract instrument response base class.
Definition: GResponse.hpp:77
bool has_gradient(const GModel &model, const GModelPar &par) const
Check whether a model parameter has an analytical gradient.
virtual const GResponse * response(void) const =0
Abstract event container class interface definition.
Time class interface definition.
const GObservation * m_parent
Observation.
npred_kern(const GObservation *parent, const GModel *model)