Parameter Fitting and Hypothesis Testing

Statistical inference engine wrapping iminuit for profiled negative log-likelihood minimisation and parameter scans.

When an analytical gradient function (model_grad) is supplied, iminuit uses it instead of finite-difference approximations.

class inference(model_nll, initial_values, list_parameters, num_unconstrained_params, model_grad=None)[source]

Bases: object

Parameters:
perform_fit(fit_strategy=2, freeze_params=[])[source]

Run MIGRAD and store best-fit parameter values.

Parameters:

  • fit_strategy (int) – Minuit strategy (0 = fast, 1 = default, 2 = robust).

  • freeze_params (list[str] | None) – List of parameter names to fix during the global fit.

Notes

After a successful fit, self.pulls_global_fit is set to a numpy.ndarray of best-fit values. This is required before calling perform_profile_scan() with doStatOnly=True.

perform_profile_scan(parameter_name='', bound_range=(0.0, 3.0), fit_strategy=2, freeze_params=[], doStatOnly=False, isConstrainedNP=False, size=100)[source]

Profile the NLL along parameter_name and plot the scan.

Parameters:

  • parameter_name (str) – Name of the parameter to scan (must be in list_parameters).

  • bound_range ((float, float)) – Scan bounds for profile fit.

  • fit_strategy (int) – Minuit strategy for the profile scans.

  • freeze_params (list[str] | None) – Parameters to fix for both scans (Stat+Syst and StatOnly).

  • doStatOnly (bool) – If True, also produce a “Stat Only” curve by fixing nuisance params (those after num_unconstrained_params) at their global-fit values.

  • isConstrainedNP (bool) – If True, change the y-axis label to t_alpha; else use t_mu.

  • size (int) – Number of scan points.

Returns:

  • scan_points (array-like) – Parameter values at which the NLL was evaluated.

  • NLL_value (array-like) – \(\Delta NLL\) values (minimum-subtracted).

  • scan_points_StatOnly (array-like, optional) – Returned only when doStatOnly=True. Scan points for the stat-only curve.

  • NLL_value_StatOnly (array-like, optional) – Returned only when doStatOnly=True. \(\Delta NLL\) for the stat-only curve.

Raises:

RuntimeError – If doStatOnly=True but perform_fit() has not been called yet.

Parameters:
Return type:

tuple[list[float]]

plot_NLL_scans(parameter_label, list_scan_points, list_nll_values, list_labels, list_linestyles, list_colors, ax=None)[source]

Plot one or more NLL profile scan curves on a single axes.

Draws each scan as a line on a shared axes, adds horizontal reference lines at \(\Delta NLL = 1, 4, 9\) corresponding to the \(1\sigma\), \(2\sigma\), and \(3\sigma\) confidence intervals, and annotates them accordingly.

Parameters:

  • parameter_label (str) – LaTeX-formatted label for the x-axis, e.g. r"$\mu$". If an empty string is passed the raw parameter_name variable is used as a fallback (note: parameter_name must be defined in the calling scope in that case).

  • list_scan_points (list of list of float) – Scan point coordinates for each curve. Each inner list must have the same length as the corresponding entry in list_nll_values. Typically the first return value of inference.perform_profile_scan().

  • list_nll_values (list of list of float) – \(\Delta NLL\) values for each curve, evaluated at the corresponding scan points. Values should already be minimum-subtracted (i.e. the minimum of each curve sits at 0).

  • list_labels (list of str) – Legend labels for each curve, e.g. ["Stat + Syst", "Stat Only"].

  • list_linestyles (list of str) – Matplotlib linestyle strings for each curve, e.g. ["solid", "dashed"].

  • list_colors (list of str) – Matplotlib colour strings for each curve, e.g. ["black", "red"].

  • ax (matplotlib.axes.Axes or None, optional) – Axes object to draw on. If None (default), a new figure and axes are created internally. Pass an existing axes to embed the plot in a larger figure layout.

Parameters:

Notes

  • All lists (list_scan_points, list_nll_values, list_labels, list_linestyles, list_colors) must have the same length; no length validation is performed.

  • The y-axis lower limit is fixed at 0.0; there is no upper limit set, so matplotlib will auto-scale to the data.

  • Reference lines at \(\Delta NLL = 1, 4, 9\) assume that the profile likelihood ratio test statistic \(t_\mu = -2\Delta\ln L\) is used, so confidence intervals are valid under Wilks’ theorem.

  • If ax is None the created figure is not returned; call plt.savefig or plt.show after this function if needed.

Examples

scan_pts, nll_vals = fitter.perform_profile_scan("mu", (0.0, 3.0))
plot_NLL_scans(
    parameter_label=r"$\mu$",
    list_scan_points=[scan_pts],
    list_nll_values=[nll_vals],
    list_labels=["Stat + Syst"],
    list_linestyles=["solid"],
    list_colors=["black"]
)
plt.show()

See also

inference.perform_profile_scan

Produces the scan arrays consumed by this function.