GammaLib  1.7.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GModel.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GModel.hpp - Abstract virtual model base 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 GModel.hpp
23  * @brief Abstract model base class interface definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GMODEL_HPP
28 #define GMODEL_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <vector>
32 #include <string>
33 #include "GBase.hpp"
34 #include "GModelPar.hpp"
35 #include "GXmlElement.hpp"
36 #include "GEnergy.hpp"
37 #include "GTime.hpp"
38 
39 /* __ Forward declarations _______________________________________________ */
40 class GEvent;
41 class GObservation;
42 
43 
44 /***********************************************************************//**
45  * @class GModel
46  *
47  * @brief Abstract model class
48  *
49  * This class implements a parametric model. The eval() method evaluates the
50  * model for a given event and observation. If the gradients parameter is set
51  * to true, the eval() method also computes analytical parameter gradients if
52  * they exist.
53  *
54  * A model has the following attributes:
55  * - @p name
56  * - @p type
57  * - @p instruments
58  * - @p ids
59  * - @p scales
60  *
61  * The model @p name is a text string that names the model. The name()
62  * methods allow setting and retrieving the model name. The model handling
63  * does not actual depend on the value of this text string.
64  *
65  * The model @p type is a text string that specifies the kind of the model.
66  * Examples are @p PointSource, @p ExtendedSource or @p DiffuseSource for
67  * sky models. The type() method allows retrieving the model type. The model
68  * handling does not actual depend on the value of this text string.
69  *
70  * The model @p instruments is a list of text strings that specifies the
71  * instruments to which the model applies. The is_valid() method will check
72  * a given instrument name against that list to verify if the model applies
73  * to an instrument. The instruments() method returns a comma separated
74  * list of all instruments. Another instance of this method allows setting
75  * the instrument list from a comma separated list. If the @p instruments
76  * list is empty, the model applies to all instruments.
77  *
78  * The model @p ids is a list of text strings that specifies the observation
79  * identifiers to which the model applies. This allows specifying of models
80  * for a specific list of observations. The is_valid() method will check
81  * a given observation identifier against that list to verify if the model
82  * applies. The ids() method returns a comma separated list of all
83  * observation identifiers. Another instance of this method allows setting
84  * the observation identifiers from a comma separated list. If the @p ids
85  * list is empty, the model applies to all observation identifiers.
86  *
87  * The model @p scales is a list of model parameters that specify an
88  * instrument dependent scaling factor. This allows to prescale a model for
89  * a given instrument. The scale() methods allow to set and to retrieve the
90  * scale factor for a specific instrument.
91  *
92  * As the class holds simply a collection of model parameters, it should
93  * neither deal with allocation and deallocation, nor with cloning of
94  * model parameters. This will be done by the classes that actually
95  * implement the model parameters.
96  ***************************************************************************/
97 class GModel : public GBase {
98 
99 public:
100  // Constructors and destructors
101  GModel(void);
102  explicit GModel(const GXmlElement& xml);
103  GModel(const GModel& model);
104  virtual ~GModel(void);
105 
106  // Operators
107  virtual GModel& operator=(const GModel& model);
108  virtual GModelPar& operator[](const int& index);
109  virtual const GModelPar& operator[](const int& index) const;
110  virtual GModelPar& operator[](const std::string& name);
111  virtual const GModelPar& operator[](const std::string& name) const;
112 
113  // Pure virtual methods
114  virtual void clear(void) = 0;
115  virtual GModel* clone(void) const = 0;
116  virtual std::string classname(void) const = 0;
117  virtual std::string type(void) const = 0;
118  virtual bool is_constant(void) const = 0;
119  virtual double eval(const GEvent& event,
120  const GObservation& obs,
121  const bool& gradients = false) const = 0;
122  virtual double npred(const GEnergy& obsEng, const GTime& obsTime,
123  const GObservation& obs) const = 0;
124  virtual void read(const GXmlElement& xml) = 0;
125  virtual void write(GXmlElement& xml) const = 0;
126  virtual std::string print(const GChatter& chatter = NORMAL) const = 0;
127 
128  // Implemented methods
129  int size(void) const;
130  int scales(void) const;
131  GModelPar& at(const int& index);
132  const GModelPar& at(const int& index) const;
133  bool has_par(const std::string& name) const;
134  bool has_scales(void) const;
135  const std::string& name(void) const;
136  void name(const std::string& name);
137  const double& ts(void) const;
138  void ts(const double& ts);
139  const bool& tscalc(void) const;
140  void tscalc(const bool& tscalc);
141  const bool& has_ts(void) const;
142  std::string instruments(void) const;
143  void instruments(const std::string& instruments);
144  GModelPar& scale(const int& index);
145  const GModelPar& scale(const int& index) const;
146  GModelPar scale(const std::string& instrument) const;
147  void scale(const GModelPar& par);
148  std::string ids(void) const;
149  void ids(const std::string& ids);
150  bool is_valid(const std::string& instruments,
151  const std::string& ids) const;
152 
153 protected:
154  // Protected methods
155  void init_members(void);
156  void copy_members(const GModel& model);
157  void free_members(void);
158  void read_attributes(const GXmlElement& xml);
159  void write_attributes(GXmlElement& xml) const;
160  std::string print_attributes(void) const;
161  void read_scales(const GXmlElement& xml);
162  void write_scales(GXmlElement& xml) const;
163 
164  // Protected members
165  std::string m_name; //!< Model name
166  std::vector<std::string> m_instruments; //!< Instruments to which model applies
167  std::vector<GModelPar> m_scales; //!< Model instrument scale factors
168  std::vector<std::string> m_ids; //!< Identifiers to which model applies
169  std::vector<GModelPar*> m_pars; //!< Pointers to all model parameters
170  bool m_has_ts; //!< Signals if TS is available
171  bool m_has_tscalc; //!< Signals if tscalc attribute is available
172  bool m_tscalc; //!< Signals if TS should be computed
173  double m_ts; //!< Test Statistic of the model
174 };
175 
176 
177 /***********************************************************************//**
178  * @brief Returns reference to model parameter by index
179  *
180  * @param[in] index Parameter index [0,...,size()-1].
181  * @return Reference to model parameter.
182  *
183  * Returns a reference to the model parameter of the specified @p index.
184  ***************************************************************************/
185 inline
186 GModelPar& GModel::operator[](const int& index)
187 {
188  // Return reference
189  return *(m_pars[index]);
190 }
191 
192 
193 /***********************************************************************//**
194  * @brief Returns reference to model parameter by index (const version)
195  *
196  * @param[in] index Parameter index [0,...,size()-1].
197  * @return Const reference to model parameter.
198  *
199  * Returns a const reference to the model parameter of the specified
200  ***************************************************************************/
201 inline
202 const GModelPar& GModel::operator[](const int& index) const
203 {
204  // Return reference
205  return *(m_pars[index]);
206 }
207 
208 
209 /***********************************************************************//**
210  * @brief Return number of parameters in model
211  *
212  * @return Number of parameters in model.
213  *
214  * Returns the number of parameters in the model.
215  ***************************************************************************/
216 inline
217 int GModel::size(void) const
218 {
219  return (int)m_pars.size();
220 }
221 
222 
223 /***********************************************************************//**
224  * @brief Return number of scale parameters in model
225  *
226  * @return Number of scale parameters in model.
227  *
228  * Returns the number of scale parameters in the model.
229  ***************************************************************************/
230 inline
231 int GModel::scales(void) const
232 {
233  return (int)m_scales.size();
234 }
235 
236 
237 /***********************************************************************//**
238  * @brief Return parameter name
239  *
240  * @return Parameter name.
241  *
242  * Returns the parameter name.
243  ***************************************************************************/
244 inline
245 const std::string& GModel::name(void) const
246 {
247  return m_name;
248 }
249 
250 
251 /***********************************************************************//**
252  * @brief Set parameter name
253  *
254  * @param[in] name Parameter name.
255  *
256  * Set the parameter name.
257  ***************************************************************************/
258 inline
259 void GModel::name(const std::string& name)
260 {
261  m_name = name;
262  return;
263 }
264 
265 /***********************************************************************//**
266  * @brief Return Test Statistic value
267  *
268  * @return Test Statistic value.
269  *
270  * Returns the Test Statistic value. The Test Statistic value is twice the
271  * difference between the log-likelihood of the null hypothesis and the
272  * alternative hypothesis.
273  ***************************************************************************/
274 inline
275 const double& GModel::ts(void) const
276 {
277  return m_ts;
278 }
279 
280 
281 /***********************************************************************//**
282  * @brief Set Test Statistic value
283  *
284  * @param[in] ts Test Statistic value.
285  *
286  * Set the Test Statistic value. The Test Statistic value is twice the
287  * difference between the log-likelihood of the null hypothesis and the
288  * alternative hypothesis.
289  ***************************************************************************/
290 inline
291 void GModel::ts(const double& ts)
292 {
293  m_ts = ts;
294  m_has_ts = true; //!< Signals that TS is now available
295  return;
296 }
297 
298 
299 /***********************************************************************//**
300  * @brief Return Test Statistic computation flag
301  *
302  * @return Test Statistic computation flag; true is Test Statistic should be
303  * computed.
304  *
305  * Returns the flag that signals whether Test Statistic values should be
306  * computed.
307  ***************************************************************************/
308 inline
309 const bool& GModel::tscalc(void) const
310 {
311  return m_tscalc;
312 }
313 
314 
315 /***********************************************************************//**
316  * @brief Set Test Statistic computation flag
317  *
318  * @param[in] tscalc Test Statistic computation flag.
319  *
320  * Set the flag that signals whether Test Statistic values should be
321  * computed.
322  ***************************************************************************/
323 inline
324 void GModel::tscalc(const bool& tscalc)
325 {
326  m_tscalc = tscalc;
327  m_has_tscalc = true; //!< Signals that tscalc is now available
328  return;
329 }
330 
331 
332 /***********************************************************************//**
333  * @brief Signals that model has scales
334  *
335  * @return True if model has scale factors.
336  ***************************************************************************/
337 inline
338 bool GModel::has_scales(void) const
339 {
340  return (!m_scales.empty());
341 }
342 
343 
344 /***********************************************************************//**
345  * @brief Signals that model has Test Statistics value
346  *
347  * @return True if model has TS value.
348  ***************************************************************************/
349 inline
350 const bool& GModel::has_ts(void) const
351 {
352  return m_has_ts;
353 }
354 
355 #endif /* GMODEL_HPP */
virtual ~GModel(void)
Destructor.
Definition: GModel.cpp:110
Abstract model class.
Definition: GModel.hpp:97
void free_members(void)
Delete class members.
Definition: GModel.cpp:656
int scales(void) const
Return number of scale parameters in model.
Definition: GModel.hpp:231
virtual bool is_constant(void) const =0
virtual void write(GXmlElement &xml) const =0
Energy value class definition.
std::string print_attributes(void) const
Print model attributes.
Definition: GModel.cpp:748
XML element node class interface definition.
double m_ts
Test Statistic of the model.
Definition: GModel.hpp:173
virtual double eval(const GEvent &event, const GObservation &obs, const bool &gradients=false) const =0
Abstract interface for the event classes.
Definition: GEvent.hpp:71
Definition of interface for all GammaLib classes.
XML element node class.
Definition: GXmlElement.hpp:47
virtual std::string classname(void) const =0
Return class name.
Time class.
Definition: GTime.hpp:54
std::string ids(void) const
Returns observation identifiers to which model applies.
Definition: GModel.cpp:492
bool m_tscalc
Signals if TS should be computed.
Definition: GModel.hpp:172
bool has_par(const std::string &name) const
Checks if parameter name exists.
Definition: GModel.cpp:280
bool m_has_ts
Signals if TS is available.
Definition: GModel.hpp:170
std::vector< GModelPar > m_scales
Model instrument scale factors.
Definition: GModel.hpp:167
bool m_has_tscalc
Signals if tscalc attribute is available.
Definition: GModel.hpp:171
std::vector< GModelPar * > m_pars
Pointers to all model parameters.
Definition: GModel.hpp:169
Model parameter class interface definition.
int size(void) const
Return number of parameters in model.
Definition: GModel.hpp:217
void init_members(void)
Initialise class members.
Definition: GModel.cpp:612
bool is_valid(const std::string &instruments, const std::string &ids) const
Verifies if model is valid for a given instrument and identifier.
Definition: GModel.cpp:560
Model parameter class.
Definition: GModelPar.hpp:87
virtual void read(const GXmlElement &xml)=0
std::vector< std::string > m_instruments
Instruments to which model applies.
Definition: GModel.hpp:166
void copy_members(const GModel &model)
Copy class members.
Definition: GModel.cpp:635
GModelPar & at(const int &index)
Returns reference to model parameter by index.
Definition: GModel.cpp:235
virtual GModelPar & operator[](const int &index)
Returns reference to model parameter by index.
Definition: GModel.hpp:186
const bool & has_ts(void) const
Signals that model has Test Statistics value.
Definition: GModel.hpp:350
const std::string & name(void) const
Return parameter name.
Definition: GModel.hpp:245
Interface class for all GammaLib classes.
Definition: GBase.hpp:52
virtual void clear(void)=0
Clear object.
std::vector< std::string > m_ids
Identifiers to which model applies.
Definition: GModel.hpp:168
virtual double npred(const GEnergy &obsEng, const GTime &obsTime, const GObservation &obs) const =0
std::string instruments(void) const
Returns instruments to which model applies.
Definition: GModel.cpp:304
GChatter
Definition: GTypemaps.hpp:33
const double & ts(void) const
Return Test Statistic value.
Definition: GModel.hpp:275
Abstract observation base class.
bool has_scales(void) const
Signals that model has scales.
Definition: GModel.hpp:338
GModelPar & scale(const int &index)
Returns reference to scale parameter by index.
Definition: GModel.cpp:363
void write_attributes(GXmlElement &xml) const
Write model attributes.
Definition: GModel.cpp:704
virtual GModel * clone(void) const =0
Clones object.
std::string m_name
Model name.
Definition: GModel.hpp:165
GModel(void)
Void constructor.
Definition: GModel.cpp:57
virtual std::string print(const GChatter &chatter=NORMAL) const =0
Print content of object.
virtual std::string type(void) const =0
void read_scales(const GXmlElement &xml)
Read instrument scales from XML element.
Definition: GModel.cpp:816
void read_attributes(const GXmlElement &xml)
Read model attributes.
Definition: GModel.cpp:668
virtual GModel & operator=(const GModel &model)
Assignment operator.
Definition: GModel.cpp:132
void write_scales(GXmlElement &xml) const
Write instrument scales into XML element.
Definition: GModel.cpp:864
const bool & tscalc(void) const
Return Test Statistic computation flag.
Definition: GModel.hpp:309
Time class interface definition.
Class that handles energies in a unit independent way.
Definition: GEnergy.hpp:48