.. include:: ../references.txt

.. _modeling:

*****************************
modeling - Models and fitting
*****************************

.. currentmodule:: gammapy.modeling

Introduction
============

`gammapy.modeling` contains all the functionality related to modeling and fitting
data. This includes spectral, spatial and temporal model classes, as well as the fit
and parameter API.

Assuming you have prepared your gamma-ray data as a set of
`~gammapy.datasets.Dataset` objects, and
stored one or more datasets in a `~gammapy.datasets.Datasets` container, you are
all set for modeling and fitting. Either via a YAML config file, or via Python
code, define the `~gammapy.modeling.models.Models` to use, which is a list of
`~gammapy.modeling.models.SkyModel` objects representing additive emission
components, usually sources or diffuse emission, although a single source can
also be modeled by multiple components if you want. The
`~gammapy.modeling.models.SkyModel` is a factorised model with a
`~gammapy.modeling.models.SpectralModel` component and a
`~gammapy.modeling.models.SpatialModel` component. Most commonly used models in
gamma-ray astronomy are built-in, see the :ref:`model-gallery`.
It is easy to create user-defined models and
datasets, Gammapy is very flexible.

The `~gammapy.modeling.Fit` class provides methods to fit, i.e. optimise
parameters and estimate parameter errors and correlations. It interfaces with a
`~gammapy.datasets.Datasets` object, which in turn is connected to a
`~gammapy.modeling.models.Models` object, which has a
`~gammapy.modeling.Parameters` object, which contains the model parameters.
Currently ``iminuit`` is used as modeling and fitting backend, in the future we
plan to support other optimiser and error estimation methods, e.g. from
``scipy``. Models can be unique for a given dataset, or contribute to multiple
datasets and thus provide links, allowing e.g. to do a joint fit to multiple
IACT datasets, or to a joint IACT and Fermi-LAT dataset. Many examples are given
in the tutorials.

Getting Started
===============
In the following you will see how to fit spectral data in OGIP format. The
format is described at :ref:`gadf:ogip`. An example dataset is available in the
``$GAMMAPY_DATA`` repo. For a description of the available fit statstics see
:ref:`fit-statistics`.


The following example shows how to fit a power law simultaneously to two
simulated crab runs using the `~gammapy.modeling.Fit` class.

.. code-block:: python

    from gammapy.datasets import SpectrumDatasetOnOff
    from gammapy.modeling import Fit
    from gammapy.modeling.models import PowerLawSpectralModel
    import matplotlib.pyplot as plt

    path = "$GAMMAPY_DATA/joint-crab/spectra/hess/"
    obs_1 = SpectrumDatasetOnOff.from_ogip_files(path + "pha_obs23523.fits")
    obs_2 = SpectrumDatasetOnOff.from_ogip_files(path + "pha_obs23592.fits")

    model = PowerLawSpectralModel(
        index=2,
        amplitude='1e-12  cm-2 s-1 TeV-1',
        reference='1 TeV',
    )

    obs_1.model = model
    obs_2.model = model

    fit = Fit([obs_1, obs_2])
    result = fit.run()

    model.parameters.covariance = result.parameters.covariance

You can check the fit results by looking at the result and model object:

.. code-block:: python

    >>> print(result)

        OptimizeResult

        backend    : minuit
        method     : minuit
        success    : True
        nfev       : 115
        total stat : 65.36
        message    : Optimization terminated successfully.


    >>> print(model)

        PowerLawSpectralModel

        Parameters:

               name     value     error        unit      min max frozen
            --------- --------- --------- -------------- --- --- ------
                index 2.781e+00 1.120e-01                nan nan  False
            amplitude 5.201e-11 4.965e-12 cm-2 s-1 TeV-1 nan nan  False
            reference 1.000e+00 0.000e+00            TeV nan nan   True

        Covariance:

               name     index   amplitude reference
            --------- --------- --------- ---------
                index 1.255e-02 3.578e-13 0.000e+00
            amplitude 3.578e-13 2.465e-23 0.000e+00
            reference 0.000e+00 0.000e+00 0.000e+00



Tutorials
=========


:ref:`tutorials` that show examples using ``gammapy.modeling``:

- `Models Tutorial <../tutorials/models.html>`__
- `Modeling and Fitting <../tutorials/modeling.html>`__
- `analysis_3d.html <../tutorials/analysis_3d.html>`__
- `spectrum_analysis.html <../tutorials/spectrum_analysis.html>`__


Reference/API
=============

.. automodapi:: gammapy.modeling
    :no-inheritance-diagram:
    :include-all-objects:

.. automodapi:: gammapy.modeling.models
    :no-inheritance-diagram:
    :include-all-objects: