Getting started
===============
Fits and the related statistical methods play an important role in particle
physics. In collider experiments, fits are used to disentangle signal and
background events and to condense the raw data into simple quantities like total
cross sections or asymmetries, which are digestible for the theory community.
In the presence of a signal fits are used to estimate the experimental
uncertainties and to prove that the observation is significant enough to claim a
discovery. In the absence of a signal, fits can be used to constrain the
parameter spaces of theoretical models that predict a signal by to combining as
much experimental data as possible. If data from several experiments is combined
to constrain a specific theoretical model one usually speaks of a *global fit*.
The comparison of theoretical predictions with experimental data is usually
complicated by the presence of uncertainties, both on the theoretical and the
experimental side. For example, the theoretical prediction for a measured
quantity may depend on a poorly known parameter (parametric uncertainty) or be
only valid within a certain approximation (theoretical systematic uncertainty).
Experimental measurements can be affected by statistical fluctuations
(statistical uncertainty) or by miscalibrations of the experimental apparatus
(experimental systematic uncertainty). To draw meaningful conclusions about a
theoretical model from experimental data all these sources of uncertainties must
modelled correctly and included in the statistical analysis.
The myFitter package is a Python module which provides a convenient, object
oriented framework for globals fits, the modelling of experimental and
theoretical errors and the inference of statements about a model's parameter
space (hypothesis tests). All information about a model (parameters,
observables, experimental and theoretical constraints, nuisance parameters etc.)
is contained in a single python class defined by the user and methods for
activating and de-activating individual parameters or constraints, fitting the
model to data, computing p-values and plotting confidence regions are provided
by the myFitter module. The framework ist taylored for non-linear regression
models (the most common type of models encountered in global fits) but can be
used for fitting arbitrary models. The main features are:
* computation maximum likelihood estimates of model parameters,
* handling of non-linear constraints on the parameter space,
* computation of profile likelihoods,
* visualisation of one and two-dimensional confidence regions (via matplotlib),
* numerical computation of p-values in likelihood ratio tests by means of
importance sampling (*myFitter method*),
* parallelisation.
Installation
------------
myFitter requires Python 2.7 and the following Python packages:
* `NumPy `_ (version 1.8 or later),
* `SciPy `_ (version 0.13 or later),
* `vegas `_ (version 2.2.1 or later),
* `cloud `_ (version 2.8.5 or later),
* `matplotlib `_ (version 1.0 or later).
To install myFitter you should download the latest source tarball from
_`http://myfitter.hepforge.org`. It will be named ``myFitter-x.y.tar.gz`` where
``x.y`` is the version number. myFitter uses the `setuptools
`_ build system. You can install
myFitter in your home directory with the following commands:
.. code-block:: none
tar -zxvf myFitter-x.y.tar.gz
cd myFitter-x.y
python setup.py install --user
To install myFitter system-wide just omit the ``--user`` option.
Examples
--------
For a quick start you can look at the following example scripts:
:download:`mymodel.py `
shows you how to define your own model class. (See :doc:`models` for
details).
:download:`fit_example.py `
shows you how to fit a model. (See :doc:`fits` for details.)
:download:`profile_example.py `
shows you how to compute profile likelihoods. (See :doc:`profile` for
details.)
:download:`toy_example_1.py `, :download:`toy_example_2.py `, :download:`toy_example_3.py `, :download:`toy_example_4.py `
show you how to run toy simulations, fill histograms, and compute p-values
numerically. (See :doc:`toys` for details.)
Running any of the examples requires the file :download:`mymodel.py
` to be present in the working directory.