ROI Optimization and Fitting

Source fitting with fermipy is generally performed with the optimize and fit methods.


fit is a wrapper on the pyLikelihood fit method and performs a likelihood fit of all free parameters of the model. This method can be used to manually optimize of the model by calling it after freeing one or more source parameters. The following example demonstrates the commands that would be used to fit the normalizations of all sources within 3 deg of the ROI center:

>>> gta.free_sources(distance=3.0,pars='norm')
>>> gta.print_params(True)

>>> o =

>>> gta.print_params(True)

By default fit will repeat the fit until a fit quality of 3 is obtained. After the fit returns all sources with free parameters will have their properties (flux, TS, NPred, etc.) updated in the ROIModel instance. The return value of the method is a dictionary containing the following diagnostic information about the fit:

fit Output Dictionary
Key Type Description
fit_quality int Fit quality parameter (3 - Full accurate covariance matrix, 2 - Full matrix, but forced positive-definite (i.e. not accurate), 1 - Diagonal approximation only, not accurate, 0 - Error matrix not calculated at all)
errors ndarray Vector of parameter errors (unscaled).
logLike float Post-fit log-likehood value.
correlation ndarray Correlation matrix between free parameters of the fit.
values ndarray Vector of best-fit parameter values (unscaled).
config dict Copy of input configuration to this method.
covariance ndarray Covariance matrix between free parameters of the fit.
dlogLike float Improvement in log-likehood value.

The fit also accepts keyword arguments which can be used to configure its behavior at runtime:

>>> o =,optimizer='NEWMINUIT',reoptimize=True)

Reference/API, **kwargs)[source]

Run the likelihood optimization. This will execute a fit of all parameters that are currently free in the model and update the charateristics of the corresponding model components (TS, Npred, etc.). The fit will be repeated N times (set with the retries parameter) until a fit quality greater than or equal to min_fit_quality is obtained. If the requested fit quality is not obtained then all parameter values will be reverted to their state prior to the execution of the fit.

  • update (bool) – Do not update the ROI model.
  • tol (float) – Set the optimizer tolerance.
  • verbosity (int) – Set the optimizer output level.
  • optimizer (str) – Set the likelihood optimizer (e.g. MINUIT or NEWMINUIT).
  • retries (int) – Set the number of times to rerun the fit when the fit quality is < 3.
  • min_fit_quality (int) – Set the minimum fit quality. If the fit quality is smaller than this value then all model parameters will be restored to their values prior to the fit.
  • reoptimize (bool) – Refit background sources when updating source properties (TS and likelihood profiles).

fit – Dictionary containing diagnostic information from the fit (fit quality, parameter covariances, etc.).

Return type:


ROI Optimization

The optimize method performs an automatic optimization of the ROI by fitting all sources with an iterative strategy.

>>> o = gta.optimize()

It is generally good practice to run this method once at the start of your analysis to ensure that all parameters are close to their global likelihood maxima.

optimization Output Dictionary
Key Type Description
logLike1 float Post-optimization log-likelihood value.
logLike0 float Pre-optimization log-likelihood value.
config dict Copy of input configuration to this method.
dlogLike float Improvement in log-likehood value.



Iteratively optimize the ROI model. The optimization is performed in three sequential steps:

  • Free the normalization of the N largest components (as determined from NPred) that contain a fraction npred_frac of the total predicted counts in the model and perform a simultaneous fit of the normalization parameters of these components.
  • Individually fit the normalizations of all sources that were not included in the first step in order of their Npred values. Skip any sources that have NPred < npred_threshold.
  • Individually fit the shape and normalization parameters of all sources with TS > shape_ts_threshold where TS is determined from the first two steps of the ROI optimization.

To ensure that the model is fully optimized this method can be run multiple times.

  • npred_frac (float) – Threshold on the fractional number of counts in the N largest components in the ROI. This parameter determines the set of sources that are fit in the first optimization step.
  • npred_threshold (float) – Threshold on the minimum number of counts of individual sources. This parameter determines the sources that are fit in the second optimization step.
  • shape_ts_threshold (float) – Threshold on source TS used for determining the sources that will be fit in the third optimization step.
  • max_free_sources (int) – Maximum number of sources that will be fit simultaneously in the first optimization step.