3.1 Specifying Experimental Inputs

To fit a model to some data you first have to instantiate the myfitter::Fitter class, which is declared in myfitter/fitter.hpp. Each Fitter object contains an object of type myfitter::LikelihoodFunction (defined in myfitter/likelihoodfunction.hpp), which can be accessed through the method

     LikelihoodFunction& Fitter::likelihood_function()

The experimental inputs are specified by adding objects of type myfitter::LikelihoodComponent to the likelihood_function() member of the Fitter class. An object of type LikelihoodComponent represents a term in the log-likelihood function (see [arXiv:1207.1446] for details). The most common types of likelihood components are defined in the header myfitter/likelihoodcomponents.hpp. Here is an example:

     #include <myfitter/fitter.hpp>
     #include <myfitter/likelihoodcomponents.hpp>
     using namespace myfitter;
     
     ...
     
     int main()
     {
         MyModel mymodel;
     
         // initialise mymodel
         ...
     
         Fitter fitter(MyModel::NOBS);
         fitter.likelihood_component().add(
             GaussianLC(MyModel::O_MYSECONDOBS, 3.0, 1.2, 0.4, 0.6));
         ...

The constructor of the Fitter class takes an integer value as argument, which specifies the dimension of the sample space, i.e. the number of observables. Only models which provide that exact number of observables (as returned by Model::nobservables()) can be fitted with the created Fitter object. The last line adds a Gaussian contribution with systematic errors to the log-likelihood function. Specifically, it states that the observables associated with the index MyModel::O_MYSECONDOBS (see MyModel example) has a measured value of 3.0 with a Gaussian statistical error of 1.2 and systematic errors of +0.4 and -0.6. In a scientific text, this might be written as 3.0\pm 1.2 (stat.) ^+0.4_-0.6 (syst.).

Note that any given observable may only contribute to one term in a LikelihoodFunction object. The LikelihoodFunction::add method will throw an exception when you try to add a likelihood component that depends on an observable which another likelihood component already depends on.

The header myfitter/likelihoodcomponents.hpp provides the following subclasses of LikelihoodComponent:

GaussianLC

This represents a single observable with a Gaussian error and (possibly) systematic errors. The constructor

          GaussianLC(int iobs, double value, double error,
                     double syst_plus=0., double syst_minus=0.)

creates a likelihood component for observable iobs with central value value, Gaussian error error and systematic errors syst_plus and syst_minus. The values of error, syst_plus and syst_minus should all be positive. If the last two arguments are omitted, the default value 0 is used.

AsymmetricGaussianLC

This represents a single observable with asymmetric Gaussian errors and (possibly) systematic errors. The constructor

          AsymmetricGaussianLC(int iobs, double value,
                               double error_plus, double error_minus,
                               double syst_plus=0.,
                               double syst_minus=0.)

creates a likelihood component for observable iobs with central value value, asymmetric Gaussian errors error_plus and error_minus and systematic errors syst_plus and syst_minus. The values of error_plus, error_minus, syst_plus and syst_minus should all be positive. If the last two arguments are omitted, the default value 0 is used.

CorrelatedGaussianLC

This represents the contribution from several observables with Gaussian errors and a non-diagonal correlation matrix. The class can not be fully initialised in the constructor. The constructor

          CorrelatedGaussianLC(int n)

creates an “empty” likelihood component for an n-dimensional sample space. Note that n is the number of observables provided by the model (i.e. the same number that is passed to the Fitter constructor) and not the number of observables contributing to the likelihood component. To initialise a CorrelatedGaussianLC object, you first have to specify the contributing observables and their central values and errors with the add() method and then set the elements of the correlation matrix with the cor() method. Here is an example:

          CorrelatedGaussianLC lc(MyModel::NOBS);
          lc.add(MyModel::O_MYFIRSTOBS, 2.3, 0.4);
          lc.add(MyModel::O_MYSECONDOBS, 5.6, 0.7);
          lc.cor(MyModel::O_MYFIRSTOBS, MyModel::O_MYSECONDOBS, 0.23);

This means that the two observables associated with the integers MyModel::O_MYFIRSTOBS and MyModel::O_MYSECONDOBS (see MyModel example) have measured values of 2.3 and 5.6, standard deviations of 0.4 and 0.7 and a correlation of 0.23. Note that only off-diagonal elements of the correlation matrix in one triangle have to be set. To add this likelihood component to the likelihood function of a Fitter instance fitter, call

          fitter.likelihood_function().add(lc);

All the information of the lc object is copied by the LikelihoodFunction::add() method and the lc object is no longer needed afterwards.