API Documentation¶

This page contains documentation which was automatically extracted from docstrings attached to the kafe2 source code. All major classes, methods and functions provided by kafe2 are documented here. For further information, or if in doubt about the exact functionality, users are invited to consult the source code itself. If you notice a mistake in the kafe2 documentation, or if you think that a particular part needs to be better documented, please open an issue on the kafe2 GitHub page.

kafe2 Wrappers¶

The easiest way to use kafe2 (as part of a Python program) is to use the wrapper functions below. These functions provide pre-configured pipelines for the most common use cases and do not require the user to manually manage objects.

kafe2.fit.util.wrapper.custom_fit(cost_function, p0=None, dp0=None, limits=None, fixed=None, constraints=None, report=False, profile=True, save=True)¶

Built-in function for directly minimizing a cost function without any explicit model, data, or errors.

Parameters:

cost_function (Callable) – The cost function to be minimized as a native Python function.
p0 (Sequence[float]) – the initial parameter values for the fit.
dp0 (Sequence[float]) – the initial parameter step size for the fit.
limits (Sequence or Sequence[Union[list, tuple]]) – limits to be applied to the model parameter. The expected format for each limit is an iterable consisting of the parameter name, the lower bound, and then the upper bound. An iterable of limits can be passed to limit multiple parameters.
fixed (Sequence or Sequence[Union[list, tuple]]) – Model parameter to be fixed. The expected format for each parameter is the parameter name followed by an optional value to which the parameter should be set prior to fixing. An iterable of (name, value) tuples can be passed to fix multiple parameters.
constraints (Sequence or Sequence[Union[list, tuple]]) – constraints to be applied to the model parameter. The expected format for each constraint is an iterable consisting of the parameter name, the parameter mean, and then the parameter uncertainty. An iterable of constraints can be passed to limit multiple parameters.
report (bool) – whether a report of the data and fit results should be printed to the console.
profile (bool) – whether the profile likelihood method should be used for asymmetric parameter errors and profile/contour plots.
save (bool) – whether the fit results should be saved to disk under results.

Returns:

the fit results.

Return type:

dict

kafe2.fit.util.wrapper.hist_fit(model_function=None, data=None, n_bins=None, bin_range=None, bin_edges=None, p0=None, dp0=None, error=None, error_rel=None, error_cor=None, error_cor_rel=None, errors_rel_to_model=True, density=True, gauss_approximation=None, limits=None, fixed=None, constraints=None, report=False, profile=True, save=True)¶

Built-in function for fitting a (probability density) function to one-dimensional data by binning the data. The uncertainty on the bins is assumed to follow a Poisson distribution. If any errors are specified then the Poisson distribution is instead approximated by a Gaussian distribution.

Parameters:

model_function (Callable) – The model function as a native Python function where the first argument denotes the independent x variable. Alternatively an already defined HistModelFunction object. Defaults to a normal distribution.
data (typing.Sequence[float] or kafe2.fit.hist.container.HistContainer) – the data for the fit. Can be either raw data, the result of np.histogram, or a kafe2.fit.hist.container.HistContainer object.
n_bins (int) – how many bins raw data should be split into.
bin_range (Sequence[float] of length 2) – the lower and upper bound for the bins specified by n_bins.
bin_edges (Sequence[float]) – explicit bin edges for raw data. If None, each bin will have the same width.
p0 (Sequence[float]) – the initial parameter values for the fit.
dp0 (Sequence[float]) – the initial parameter step size for the fit.
error (float or Sequence[float]) – uncorrelated absolute error on the bin heights.
error_rel (float or Sequence[float]) – uncorrelated relative error on the bin heights.
error_cor (float or Sequence[float]) – correlated absolute error on the bin heights.
error_cor_rel (float or Sequence[float]) – correlated relative error on the bin heights.
errors_rel_to_model (bool) – whether the relative y errors should be relative to the model. Otherwise they are relative to the data.
density (bool) – whether the model is a probability density function and the data should be normalized to match it.
limits (Sequence or Sequence[Union[list, tuple]]) – limits to be applied to the model parameter. The expected format for each limit is an iterable consisting of the parameter name, the lower bound, and then the upper bound. An iterable of limits can be passed to limit multiple parameters.
fixed (Sequence or Sequence[Union[list, tuple]]) – Model parameter to be fixed. The expected format for each parameter is the parameter name followed by an optional value to which the parameter should be set prior to fixing. An iterable of (name, value) tuples can be passed to fix multiple parameters.
constraints (Sequence or Sequence[Union[list, tuple]]) – constraints to be applied to the model parameter. The expected format for each constraint is an iterable consisting of the parameter name, the parameter mean, and then the parameter uncertainty. An iterable of constraints can be passed to limit multiple parameters.
report (bool) – whether a report of the data and fit results should be printed to the console.
profile (bool) – whether the profile likelihood method should be used for asymmetric parameter errors and profile/contour plots.
save (bool) – whether the fit results should be saved to disk under results.

Returns:

the fit results.

Return type:

dict

kafe2.fit.util.wrapper.indexed_fit(model_function=None, data=None, p0=None, dp0=None, error=None, error_rel=None, error_cor=None, error_cor_rel=None, errors_rel_to_model=True, limits=None, fixed=None, constraints=None, report=False, profile=True, save=True)¶

kafe2.fit.util.wrapper.unbinned_fit(model_function=None, data=None, p0=None, dp0=None, limits=None, fixed=None, constraints=None, report=False, profile=True, save=True)¶

Built-in function for directly fitting a probability density function to one-dimensional data without binning the data.

Parameters:

model_function (Callable) – The model function as a native Python function where the first argument denotes the independent x variable. Alternatively an already defined ModelFunctionBase object. Defaults to a straight line.
data (Sequence[float]) – the data values for the fit. Must be one-dimensional.
p0 (Sequence[float]) – the initial parameter values for the fit.
dp0 (Sequence[float]) – the initial parameter step size for the fit.
limits (Sequence or Sequence[Union[list, tuple]]) – limits to be applied to the model parameter. The expected format for each limit is an iterable consisting of the parameter name, the lower bound, and then the upper bound. An iterable of limits can be passed to limit multiple parameters.
fixed (Sequence or Sequence[Union[list, tuple]]) – Model parameter to be fixed. The expected format for each parameter is the parameter name followed by an optional value to which the parameter should be set prior to fixing. An iterable of (name, value) tuples can be passed to fix multiple parameters.
constraints (Sequence or Sequence[Union[list, tuple]]) – constraints to be applied to the model parameter. The expected format for each constraint is an iterable consisting of the parameter name, the parameter mean, and then the parameter uncertainty. An iterable of constraints can be passed to limit multiple parameters.
report (bool) – whether a report of the data and fit results should be printed to the console.
profile (bool) – whether the profile likelihood method should be used for asymmetric parameter errors and profile/contour plots.
save (bool) – whether the fit results should be saved to disk under results.

Returns:

the fit results.

Return type:

dict

kafe2.fit.util.wrapper.xy_fit(model_function=None, x_data=None, y_data=None, p0=None, dp0=None, x_error=None, y_error=None, x_error_rel=None, y_error_rel=None, x_error_cor=None, y_error_cor=None, x_error_cor_rel=None, y_error_cor_rel=None, errors_rel_to_model=True, limits=None, fixed=None, constraints=None, report=False, profile=None, save=True)¶

Built-in function for fitting a model function to xy data.

Interpretation of x_error, y_error, x_error_rel, and y_error_rel: If the input error is a simple float it is broadcast across the entire data vector. If the input error is a one-dimensional vector it is interpreted as a pointwise error vector. If the input error is a two-dimensional matrix it is interpreted as a covariance matrix.

Interpretation of x_error_cor, y_error_cor, x_error_cor_rel, and y_error_cor_rel: If the input error is a simple float it is broadcast across the entire data vector. If the input error is a one-dimensional vector then each individual value is added as a separate error that is being broadcast across the entire data vector.

Parameters:

model_function (Callable) – The model function as a native Python function where the first argument denotes the independent x variable. Alternatively an already defined ModelFunctionBase object. Defaults to a straight line.
x_data (Sequence[float]) – the x data values for the fit. Must be one-dimensional.
y_data (Sequence[float]) – the y data values for the fit. Must be one-dimensional.
p0 (Sequence[float]) – the initial parameter values for the fit.
dp0 (Sequence[float]) – the initial parameter step size for the fit.
x_error (float or Sequence[float]) – uncorrelated absolute x error.
y_error (float or Sequence[float]) – uncorrelated absolute y error.
x_error_rel (float or Sequence[float]) – uncorrelated relative x error.
y_error_rel (float or Sequence[float]) – uncorrelated relative y error.
x_error_cor (float or Sequence[float]) – correlated absolute x error.
y_error_cor (float or Sequence[float]) – correlated absolute y error.
x_error_cor_rel (float or Sequence[float]) – correlated relative x error.
y_error_cor_rel (float or Sequence[float]) – correlated relative y error.
errors_rel_to_model (bool) – whether the relative y errors should be relative to the model. Otherwise they are relative to the data.
limits (Sequence or Sequence[Union[list, tuple]]) – limits to be applied to the model parameter. The expected format for each limit is an iterable consisting of the parameter name, the lower bound, and then the upper bound. An iterable of limits can be passed to limit multiple parameters.
fixed (Sequence or Sequence[Union[list, tuple]]) – Model parameter to be fixed. The expected format for each parameter is the parameter name followed by an optional value to which the parameter should be set prior to fixing. An iterable of (name, value) tuples can be passed to fix multiple parameters.
constraints (Sequence or Sequence[Union[list, tuple]]) – constraints to be applied to the model parameter. The expected format for each constraint is an iterable consisting of the parameter name, the parameter mean, and then the parameter uncertainty. An iterable of constraints can be passed to limit multiple parameters.
report (bool) – whether a report of the data and fit results should be printed to the console.
profile (bool) – whether the profile likelihood method should be used for asymmetric parameter errors and profile/contour plots.
save (bool) – whether the fit results should be saved to disk under results.

Returns:

the fit results.

Return type:

dict

kafe2.fit.util.wrapper.plot(fits=-1, x_label=None, y_label=None, data_label=None, model_label=None, error_band_label=None, x_range=None, y_range=None, x_scale=None, y_scale=None, x_ticks=None, y_ticks=None, parameter_names=None, model_name=None, model_expression=None, font_scale=1.0, legend=True, fit_info=True, error_band=True, profile=None, plot_profile=None, show=True, save=True)¶

Plots kafe2 fits.

Parameters:

fits (int or FitBase or Sequence[FitBase]) – which kafe2 fits to use for the plot. A positive integer is interpreted as the fit with the given index that has been performed (with wrappers) since the program started. A negative integer -n is interpreted as the last n fits. kafe2 fit objects are used directly.
x_label (str) – the x axis label.
y_label (str) – the y axis label.
data_label (str or Sequence[str]) – the data label(s) in the legend.
model_label (str or Sequence[str]) – the model label(s) in the legend (under data label).
error_band_label (str or Sequence[str]) – the error band label(s) in the legend.
x_range (Sequence[float], len(x_range) == 2) – x range for the plot.
y_range (Sequence[float], len(y_range) == 2) – y range for the plot.
x_scale ("linear" or "log") – the scale to use for the x axis.
y_scale ("linear" or "log") – the scale to use for the y axis.
x_ticks (Sequence[float]) – the ticks at which to show values on the x axis.
y_ticks (Sequence[float]) – the ticks at which to show values on the y axis.
parameter_names (dict) – custom parameter LaTeX names to display in the plot. The dictionary keys are the regular parameter names and the dictionary values are the names to show in the plot.
model_name (str or Sequence[str]) – the model LaTeX name(s) in the legend (in the mathematical expression of the model function).
model_expression (str or Sequence[str]) – the model LaTeX expression(s) in the legend.
legend (bool) – whether the legend should be shown.
fit_info (bool) – whether the fit information (fit results, goodness of fit) should be shown.
error_band (bool) – whether the model error band should be shown.
profile (bool) – whether the profile likelihood method should be used for asymmetric parameter errors and profile/contour plots.
plot_profile (bool) – whether the profile plots should be created.
show (bool) – whether the plots should be shown.
save (bool) – whether the plots should be saved to disk under results.
font_scale (float) – multiply font size by this amount.

Returns:

a kafe2 plot object containing the relevant matplotlib plots.

Return type:

Plot

kafe2.fit.util.wrapper.k2Fit(func, x, y, sx=None, sy=None, srelx=None, srely=None, xabscor=None, yabscor=None, xrelcor=None, yrelcor=None, ref_to_model=True, constraints=None, p0=None, dp0=None, limits=None, plot=True, axis_labels=['x-data', 'y-data'], data_legend='data', model_expression=None, model_name=None, model_legend='model', model_band='$\\pm 1 \\sigma$', fit_info=True, plot_band=True, asym_parerrs=True, plot_cor=False, showplots=True, quiet=True)¶

Legacy function for backwards compatibility with PhyPraKit. New code should not use this function. Fits a model to xy data and plots the results.

Interpretation of sx, sy, srelx, and srely: If the input error is a simple float it is broadcast across the entire data vector. If the input error is a one-dimensional vector it is interpreted as a pointwise error vector. If the input error is a two-dimensional matrix it is interpreted as a covariance matrix.

Interpretation of xabscor, yabscor, xrelcor, and yrelcor: If the input error is a simple float it is broadcast across the entire data vector. If the input error is a one-dimensional vector then each individual value is added as a separate error that is being broadcast across the entire data vector.

Parameters:

func (Callable) – The model function as a native Python function where the first argument denotes the independent x variable. Alternatively an already defined ModelFunctionBase object. Defaults to a straight line.
x (Sequence[float]) – the x data values for the fit. Must be one-dimensional.
y (Sequence[float]) – the y data values for the fit. Must be one-dimensional.
sx (float or Sequence[float]) – uncorrelated absolute x error.
sy (float or Sequence[float]) – uncorrelated absolute y error.
srelx (float or Sequence[float]) – uncorrelated relative x error.
srely (float or Sequence[float]) – uncorrelated relative y error.
xabscor (float or Sequence[float]) – correlated absolute x error.
yabscor (float or Sequence[float]) – correlated absolute y error.
xrelcor (float or Sequence[float]) – correlated relative x error.
yrelcor (float or Sequence[float]) – correlated relative y error.
ref_to_model (bool) – whether the relative y errors should be relative to the model. Otherwise they are relative to the data.
constraints (Sequence or Sequence[Union[list, tuple]]) – constraints to be applied to the model parameter. The expected format for each constraint is an iterable consisting of the parameter name, the parameter mean, and then the parameter uncertainty. An iterable of constraints can be passed to limit multiple parameters.
p0 (Sequence[float]) – the initial parameter values for the fit.
dp0 (Sequence[float]) – the initial parameter step size for the fit.
limits (Sequence or Sequence[Union[list, tuple]]) – limits to be applied to the model parameter. The expected format for each limit is an iterable consisting of the parameter name, the lower bound, and then the upper bound. An iterable of limits can be passed to limit multiple parameters.
plot (bool) – whether the fit results should be plotted.
axis_labels (Sequence[str]) – the labels for the x and y axis.
data_legend (str) – the data label in the legend.
model_expression (str) – the model LaTeX expression in the legend.
model_name (str) – the model LaTeX name in the legend (in the mathematical expression of the model function).
model_legend (str) – the model label in the legend (under data label).
model_band (str) – the error band label in the legend.
fit_info (bool) – whether the fit information (fit results, goodness of fit) should be shown.
plot_band (bool) – whether the model error band should be shown.
asym_parerrs (bool) – whether the profile likelihood method should be used for asymmetric parameter errors.
plot_cor (bool) – whether the profile plots should be created.
showplots (bool) – whether the plots should be shown.
report (bool) – whether the report of the data and fit results should be suppressed.

Returns:

a tuple containing the parameter values, the parameter errors, the parameter correlation matrix, and the minimal $\chi^2$ cost function value.

Return type:

tuple

kafe2 Object-Oriented Programming¶

Parameter Estimation Tools: `fit`¶

The kafe2.fit module provides an object-oriented toolkit for estimating model parameters from data (“fitting”).

It distinguishes between a number of different data types:

xy data (dedicated submodule: xy),
series of indexed measurements (dedicated submodule: indexed),
histograms (dedicated submodule: histogram),
raw 1D data using the method of maximum likelihood (“unbinned fit”, dedicated submodule: histogram), and
direct minimization of a cost function (dedicated submodule: custom).

Each of the above data types has its own particularities when it comes to fitting. The main difference is due to the way uncertainties can be defined and interpreted for each type of data and how the fit results are presented.

XY Data¶

For xy data, one data set consists of a list of $N$ distinct $y$ measurements $d_i$ with the (discrete) index $i$ ranging from $0$ to $N-1$ . The measurements were taken at $x$ values $x_i$ . For each measurement in the series, one or more uncertainty sources can be defined, each being a numerical estimate of how much the respective measurement has fluctuated from the “true values”. Correlations between uncertainties on separate measurements $d_i$ and $d_j$ can also be taken into account by using covariance/correlation matrices.

Additional uncertainites on $x_i$ can also be defined. When fitting an xy model to data they are converted to $y$ uncertainties via multiplication with the derivative of the model function by $x$ . When plotting the result of xy fits, the model function is displayed as a continuous function of $x$ , and an error band can be computed to reflect the model uncertainty, as determined by propagating the parameter uncertainties onto the y axis.

The following objects are provided for handling xy data:

XYContainer: data container for storing xy data
XYParametricModel: corresponding model
XYFit: a fit of a parametric model to xy data

Indexed data¶

Compared to xy data indexed data no longer has an explicit x axis. The data simply appears as an indexed list of data points. As a consequence the model function does not expect an independent variable.

The following objects are provided for handling indexed data, as described above:

IndexedContainer: data container for storing indexed data
IndexedParametricModel: corresponding model
IndexedFit: a fit of a parametric model to indexed data

Histograms¶

kafe2 is also able to handle histograms. Histograms organize measurements whose values can fall anywhere across a continuum of values into a number of discrete regions or “bins”. Typically, the continuous “measurement space” (a closed real interval $[x_{\rm min}, x_{\rm max}]$ ) is subdivided into a sequence of successive intervals at the “bin edges” $x_{\rm min} < x_1 < x_2 < \ldots < x_{\rm max}$ . Whenever a measurement falls into one of the bins, the value of that histogram bin is incremented by one. A histogram is completely defined by its bin edges and the bin values.

Note

The bin numbering starts at $1$ for the first bin and ends at $N$ , where $N$ is defined as the size of the histogram. The bin numbers $0$ and $N+1$ refer to the underflow (below $x_{\rm min}$ ) and overflow bin (above $x_{\rm max}$ ), respectively.

Defining a parametric model for histograms is not as straightforward as for xy and indexed data. Seeing as they keep track of the number of entries in different intervals of the continuum, the bin values can be interpreted using probability theory.

As the number of entries approaches infinity, the number of entries $n$ in the bin covering an interval $[a, b)$ , divided by the total number of entries $N_{\rm E}$ , will approach the probablity of an event landing in that bin:

$\lim_{N_{\rm E}\rightarrow\infty} \frac{n}{N_{\rm E}} = \int_a^b f(x)\,{\rm d}x = F(b) - F(a)$

In the above formula, $f(x)$ is the probability density function, and $F(x)$ is an antiderivative of $f$ (for example the cumulative distribution function).

Using the above relation, the model prediction $m$ for the bin $[a, b)$ can be defined as:

$m = N_{\rm E} \int_a^b f(x)\,{\rm d}x = N_{\rm E} \left(F(b) - F(a)\right)$

This means that, for histograms, the model density $f(x)$ needs to be specified as the model function. The model is then calculated by numerically integrating this function over each bin.

An alternative would be to specify the model density antiderviative $F$ alongside the model, so that the model can be calculated as a simple difference, rather than as an integral.

The following objects are provided for handling histograms:

HistContainer: data container for storing histograms
HistParametricModel: corresponding model
HistFit: a fit of a parametric model to histograms

Unbinned¶

If data is treated as unbinned the model function $f(x)$ is interpreted as a model density function. The cost function value $C$ is then directly calculated as the negative log-likelihood of the data given said PDF:

$C = - 2 \sum_{i=0}^{N-1} \ln f(x_i) .$

An unbinned fit is the edge case of a histogram fit for as the individual bins become infinitessimally thin.

The following objects are provided for handling unbinned data:

UnbinnedContainer: data container for storing unbinned data
UnbinnedParametricModel: corresponding model
UnbinnedFit: a fit of a parametric model to unbinned data

Custom¶

Lets the user directly define a cost function. Since this fit type does not have explicit data the fit results cannot be plotted automatically.

The following objects are provided for custom fits:

CustomFit: a fit for minimizing a cost function

Plots¶

For creating graphical representations of fits, the Plot is provided. It can be instantiated with any fit object (or list of fit objects) as an argument and will produce one or more plots accordingly using matplotlib.

synopsis:: This module contains specialized objects for storing measurement data, defining and fitting parametric models to these data and producing graphical representations (“plots”) of the result. It relies on the kafe2.core module for basic functionality.

Tools for Fitting xy Data: `xy`¶

This submodule provides the necessary objects for parameter estimation using data consisting of ordered xy pairs. This fit type is used for most cases e.g. when performing fits for the first time or in physics laboratory courses.

synopsis:: This submodule provides the necessary objects for parameter estimation using data consisting of ordered xy pairs.

class kafe2.fit.xy.XYContainer(x_data, y_data, dtype=<class 'float'>)¶

Bases: IndexedContainer

This object is a specialized data container for xy data.

Construct a container for xy data:

Parameters:

x_data (Sequence[dtype]) – 1D array of measurement x values.
y_data (Sequence[dtype]) – 1D array of measurement y values.
dtype (type) – Data type of the measurements.

property size¶

Number of data points.

Return type:: int

property data¶

2D array with shape (2, size) containing a copy of the data stored in this container.

Return type:: numpy.ndarray

property x¶

1D array of length [size] containing the x data.

Return type:: numpy.ndarray

property x_err¶

1D array containing the absolute total data x uncertainties.

Return type:: numpy.ndarray

property x_cov_mat¶

2D array of shape (size, size) containing the absolute data x covariance matrix.

Return type:: numpy.ndarray

property x_cov_mat_inverse¶

2D array of shape (size, size) containing the inverse of the absolute data x covariance matrix. None if singular.

Return type:: numpy.ndarray or None

property x_cor_mat¶

2D array of shape (size, size) containing the absolute data x correlation matrix.

Return type:: numpy.ndarray

property y¶

1D array of length size containing the y data.

Return type:: numpy.ndarray

property y_err¶

1D array of length size containing the absolute total data y uncertainties.

Return type:: numpy.ndarray

property y_cov_mat¶

2D array of shape (size, size) containing the absolute data y covariance matrix.

Return type:: numpy.ndarray

property y_cov_mat_inverse¶

2D array of shape (size, size) containing the inverse of absolute data y covariance matrix. None if singular.

Return type:: numpy.ndarray

property y_cor_mat¶

2D array of shape (size, size) containing the absolute data y correlation matrix.

Return type:: numpy.ndarray

property x_range¶

Minimum and maximum values of the x data.

Return type:: tuple[float, float]

property y_range¶

Minimum and maximum values of the y data.

Return type:: tuple[float, float]

add_error(axis, err_val, name=None, correlation=0, relative=False)¶

Add an uncertainty source for an axis to the data container.

Parameters:

axis (str or int) – 'x'/0 or 'y'/1
err_val (float or Sequence[float]) – Pointwise uncertainties or a single uncertainty for all data points.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
correlation (float) – Correlation coefficient between any two distinct data points.
relative (bool) – If True, err_val will be interpreted as a relative uncertainty.

Returns:

An error id uniquely identifying the created error source.

Return type:

str

add_matrix_error(axis, err_matrix, matrix_type, name=None, err_val=None, relative=False)¶

Add a matrix uncertainty source for an axis to the data container.

Parameters:

axis (str or int) – 'x'/0 or 'y'/1
err_matrix (numpy.ndarray) – 2D array of shape (size, size) containing the covariance or correlation matrix
matrix_type (str) – One of 'covariance'/'cov' or 'correlation'/'cor'.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
err_val (Sequence[float]) – The pointwise uncertainties. This is mandatory if only a correlation matrix is given.
relative (bool) – If True, the covariance matrix and/or err_val will be interpreted as a relative uncertainty.

Returns:

An error id uniquely identifying the created error source.

Return type:

str

get_total_error(axis)¶

Get the error object representing the total uncertainty for a specific axis.

Parameters:: axis (str or int) – 'x'/0 or 'y'/1
Returns:: Error object representing the total uncertainty.
Return type:: kafe2.core.error.MatrixGaussianError

property has_x_errors¶

True if at least one x uncertainty source is defined for the data container.

Return type:: bool

property has_uncor_x_errors¶

True if at least one x uncertainty source, which is not fully correlated, is defined for the data container.

Return type:: bool

property has_y_errors¶

True if at least one x uncertainty source is defined for the data container.

Return type:: bool

class kafe2.fit.xy.XYCostFunction_Chi2(errors_to_use='covariance', fallback_on_singular=True, axes_to_use='xy', add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction_Chi2

Built-in least-squares cost function for xy data.

Parameters:

errors_to_use (str or None) – Which errors to use when calculating $\chi^2$ . This is either ‘covariance’`, 'pointwise' or None.
axes_to_use – The errors for the given axes are taken into account when calculating $\chi^2$ . Either 'y' or 'xy'
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.xy.XYCostFunction_GaussApproximation(errors_to_use='covariance', axes_to_use='xy', add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction_GaussApproximation

Built-in Gaussian approximation of the Poisson negative log-likelihood cost function for xy data.

Parameters:

errors_to_use (str) – Which errors to use when calculating $\chi^2$ . This is either ‘covariance’`, 'pointwise'.
axes_to_use – The errors for the given axes are taken into account when calculating $\chi^2$ . Either 'y' or 'xy'
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.xy.XYCostFunction_NegLogLikelihood(data_point_distribution='poisson', ratio=False, axes_to_use='xy')¶

Bases: CostFunction_NegLogLikelihood

Base class for built-in negative log-likelihood cost function.

In addition to the measurement data and model predictions, likelihood-fits require a probability distribution describing how the measurements are distributed around the model predictions. This built-in cost function supports two such distributions: the Poisson and Gaussian (normal) distributions.

In general, a negative log-likelihood cost function is defined as the double negative logarithm of the product of the individual likelihoods of the data points.

The likelihood ratio is defined as ratio of the likelihood function for each individual observation, divided by the so-called marginal likelihood.

Parameters:

data_point_distribution (str) – Which type of statistics to use for modelling the distribution of individual data points. Either 'poisson' or 'gaussian'.
ratio (bool) – If True, divide the likelihood by the marginal likelihood.

class kafe2.fit.xy.XYFit(xy_data, model_function=<function linear_model>, cost_function='chi2', minimizer=None, minimizer_kwargs=None, dynamic_error_algorithm='nonlinear')¶

Bases: FitBase

Construct a fit of a model to xy data.

Parameters:

xy_data (XYContainer or Sequence) – A XYContainer or a raw 2D array of shape (2, N) containing the measurement data.
model_function (Callable) – The model function as a native Python function where the first argument denotes the independent x variable. Alternatively an already defined XYModelFunction object. Defaults to a straight line.
cost_function (str or Callable) – The cost function this fit uses to find the best parameters.
minimizer (str or None) – The minimizer to use for fitting. Either None, "iminuit", "tminuit", or "scipy".
minimizer_kwargs (dict) – Dictionary with kwargs for the minimizer.

CONTAINER_TYPE¶: alias of XYContainer

MODEL_TYPE¶: alias of XYParametricModel

MODEL_FUNCTION_TYPE¶: alias of ModelFunctionBase

PLOT_ADAPTER_TYPE¶: alias of XYPlotAdapter

RESERVED_NODE_NAMES = {'cost', 'total_cor_mat', 'total_cor_mat_inversex_data_cov_mat', 'total_cov_mat', 'total_error', 'x_cor_mat', 'x_cov_mat', 'x_cov_mat_inverse', 'x_error', 'y_data', 'y_data_cor_mat', 'y_data_cov_mat', 'y_data_cov_mat_inverse', 'y_data_error', 'y_model', 'y_model_cor_mat', 'y_model_cov_mat', 'y_model_cov_mat_inverse', 'y_model_error'}¶

X_ERROR_ALGORITHMS = ('iterative linear', 'nonlinear')¶

property has_x_errors¶

True` if at least one x uncertainty source has been defined.

Return type:: bool

property has_y_errors¶

True` if at least one y uncertainty source has been defined

Return type:: bool

property x_data¶

1D array containing the measurement x values.

Return type:: numpy.ndarray[float]

property x_model¶

.x_data for an: XYFit.

Return type:: numpy.ndarray[float]
Type:: 1D array containing the model x values. The same as
Type:: py;obj

property y_data¶

1D array containing the measurement y values.

Return type:: numpy.ndarray[float]

property model¶

2D array of shape (2, N) containing the x and y model values

Return type:: numpy.ndarray

property x_data_error¶

1D array containing the pointwise x data uncertainties

Return type:: numpy.ndarray[float]

property y_data_error¶

1D array containing the pointwise y data uncertainties

Return type:: numpy.ndarray[float]

property data_error¶

1D array containing the pointwise xy uncertainties projected onto the y axis.

Return type:: numpy.ndarray[float]

property x_data_cov_mat¶

2D array of shape (N, N) containing the data x covariance matrix.

Return type:: numpy.ndarray

property y_data_cov_mat¶

2D array of shape (N, N) containing the data y covariance matrix.

Return type:: numpy.ndarray

property data_cov_mat¶

2D array of shape (N, N) containing the data xy covariance matrix (projected onto the y axis).

Return type:: numpy.ndarray

property x_data_cov_mat_inverse¶

2D array of shape (N, N) containing the inverse of the data x covariance matrix or None if singular.

Return type:: numpy.ndarray or None

property y_data_cov_mat_inverse¶

2D array of shape (N, N) containing the inverse of the data y covariance matrix or None if singular.

Return type:: numpy.ndarray or None

property data_cov_mat_inverse¶

2D array of shape (N, N) containing the inverse of the data xy covariance matrix projected onto the y axis. None if singular.

Return type:: numpy.ndarray or None

property x_data_cor_mat¶

2D array of shape (N, N) containing the data x correlation matrix.

Return type:: numpy.ndarray

property y_data_cor_mat¶

2D array of shape (N, N) containing the data y correlation matrix.

Return type:: numpy.ndarray

property data_cor_mat¶

2D array of shape (N, N) containing the data xy correlation matrix projected onto the y axis.

Return type:: numpy.ndarray

property y_model¶

1D array of y model predictions for the data points.

Return type:: numpy.ndarray[float]

property x_model_error¶

1D array of pointwise model x uncertainties.

Return type:: numpy.ndarray[float]

property y_model_error¶

1D array of pointwise model y uncertainties.

Return type:: numpy.ndarray[float]

property model_error¶

1D array of pointwise model xy uncertainties projected onto the y axis.

Return type:: numpy.ndarray[float]

property x_model_cov_mat¶

2D array of shape (N, N) containing the model x covariance matrix.

Return type:: numpy.ndarray

property y_model_cov_mat¶

2D array of shape (N, N) containing the model y covariance matrix.

Return type:: numpy.ndarray

property model_cov_mat¶

2D array of shape (N, N) containing the model xy covariance matrix projected onto the y axis.

Return type:: numpy.ndarray

property x_model_cov_mat_inverse¶

2D array of shape (N, N) containing the inverse of the model x covariance matrix or None if singular.

Return type:: numpy.ndarray or None

property y_model_cov_mat_inverse¶

2D array of shape (N, N) containing the inverse of the model y covariance matrix or None if singular.

Return type:: numpy.ndarray

property model_cov_mat_inverse¶

2D array of shape (N, N) containing the inverse of the model xy covariance matrix projected onto the y axis. None` if singular.

Return type:: numpy.ndarray

property x_model_cor_mat¶

2D array of shape (N, N) containing the model x correlation matrix.

Return type:: numpy.ndarray

property y_model_cor_mat¶

2D array of shape (N, N) containing the model y correlation matrix.

Return type:: numpy.ndarray

property model_cor_mat¶

2D array of shape (N, N) containing the model xy correlation matrix projected onto the y axis.

Return type:: numpy.ndarray

property x_total_error¶

1D array of total pointwise x uncertainties.

Return type:: numpy.ndarray[float]

property y_total_error¶

1D array of total pointwise y uncertainties

Return type:: numpy.ndarray[float]

property total_error¶

1D array of the total pointwise xy uncertainties projected onto the y axis.

Return type:: numpy.ndarray[float]

property x_total_cov_mat¶

2D array of shape (N, N) containing the total x covariance matrix.

Return type:: numpy.ndarray

property y_total_cov_mat¶

2D array of shape (N, N) containing the total y covariance matrix.

Return type:: numpy.ndarray

property total_cov_mat¶

2D array of shape (N, N) containing the total xy covariance matrix projected onto the y axis.

Return type:: numpy.ndarray

property x_total_cov_mat_inverse¶

2D array of shape (N, N) containing inverse of the total x covariance matrix. None if singular.

Return type:: numpy.ndarray

property y_total_cov_mat_inverse¶

2D array of shape (N, N) containing inverse of the total y covariance matrix. None if singular.

Return type:: numpy.ndarray

property total_cov_mat_inverse¶

2D array of shape (N, N) containing theinverse of the total xy covariance matrix projected onto the y axis. None if singular.

Return type:: numpy.ndarray

property x_total_cor_mat¶

2D array of shape (N, N) containing the total x correlation matrix.

Return type:: numpy.ndarray

property y_total_cor_mat¶

2D array of shape (N, N) containing the total y correlation matrix.

Return type:: numpy.ndarray

property x_range¶

Minimum and maximum values of the x measurement data.

Return type:: tuple[float, float]

property y_range¶

Minimum and maximum values of the y measurement data.

Return type:: tuple[float, float]

add_error(axis, err_val, name=None, correlation=0, relative=False, reference='data')¶

Add an uncertainty source for an axis to the data container.

Parameters:

axis (str or int) – 'x'/0 or 'y'/1
err_val (float or Sequence[float]) – Pointwise uncertainties or a single uncertainty for all data points.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
correlation (float) – Correlation coefficient between any two distinct data points.
relative (bool) – If True, err_val will be interpreted as a relative uncertainty.
reference (str) – Which reference values to use when calculating absolute errors from relative errors. Either 'data' or 'model'.

Returns:

An error id uniquely identifying the created error source.

Return type:

str

add_matrix_error(axis, err_matrix, matrix_type, name=None, err_val=None, relative=False, reference='data')¶

Add a matrix uncertainty source for an axis to the data container.

Parameters:

axis (str or int) – 'x'/0 or 'y'/1
err_matrix (numpy.ndarray) – 2D array of shape (size, size) containing the covariance or correlation matrix
matrix_type (str) – One of 'covariance'/'cov' or 'correlation'/'cor'.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
err_val (Sequence[float]) – The pointwise uncertainties. This is mandatory if only a correlation matrix is given.
relative (bool) – If True, the covariance matrix and/or err_val will be interpreted as a relative uncertainty.
reference (str) – Which reference values to use when calculating absolute errors from relative errors. Either 'data' or 'model'.

Returns:

An error id uniquely identifying the created error source.

Return type:

str

eval_model_function(x=None, model_parameters=None)¶

Evaluate the model function.

Parameters:

x (numpy.ndarray[float]) – 1D array containing the values of x at which to evaluate the model function. If None, the data x values x_data are used.
model_parameters (Collection[float]) – The model parameter values. If None, the current values parameter_values are used.

Returns:

Model function values at the given x-values.

Return type:

numpy.ndarray[float]

eval_model_function_derivative_by_parameters(x=None, model_parameters=None, par_dx=None)¶

Evaluate the derivative of the model function with respect to the model parameters.

Parameters:

x (numpy.ndarray[float]) – 1D array containing the x values at which to evaluate the model function. If None, the data x values x_data are used.
model_parameters (Collection[float]) – 1D array containing the model parameter values. If None, the current values parameter_values are used.
par_dx (Collection[float]) – 1D array with length pars containing the numeric differentiation step size for each parameter. If None and a fit has been performed, 1% of the parameter uncertainties is used.

Returns:

2D array of shape (par, N) containing the model function derivatives for each parameter at the given x values.

Return type:

numpy.ndarray[numpy.ndarray[float]]

error_band(x=None)¶

Calculate the symmetric model uncertainty at every given point x. This is only possible after a fit has been performed with the do_fit method.

Parameters:: x (numpy.ndarray[float]) – 1D array containing the values of x at which to calculate the model uncertainty.
Returns:: 1D array containing the model uncertainties at the given x values.
Return type:: numpy.ndarray[float]

class kafe2.fit.xy.XYFitEnsemble(n_experiments, x_support, model_function, model_parameters, cost_function=<kafe2.fit.xy.cost.XYCostFunction_Chi2 object>, requested_results=None)¶

Bases: FitEnsembleBase

Object for generating ensembles of fits to xy pseudo-data generated according to the specified uncertainty model.

After constructing an XYFitEnsemble object, an error model should be added to it. This is done as for XYFit objects by using the add_error or add_matrix_error methods.

Once an uncertainty model is provided, the fit ensemble can be generated by using the run method. This method starts by generating a pseudo-dataset in such a way that the empirical distribution of the data corresponds to the specified uncertainty model. It then fits the model to the pseudo-data and extracts information from the fit, such as the resulting parameter values or the value of the cost function at the minimum. This is repeated a large number of times in order to evaluate the whole ensemble in a statistically meaningful way.

The ensemble result can be visualized by using the plot_results method.

Construct an XYFitEnsemble object.

Parameters:

n_experiments (int) – Number of pseudo experiments to perform.
x_support (Sequence[float]) – x values to use as support for calculating the “true” model (“true” x).
model_function (Callable) – The model function. Either a XYModelFunction object or an unwrapped native Python function.
model_parameters (Sequence[float]) – Parameters of the “true” model
cost_function (Callable) – The cost function used for the fits. Either a CostFunctionBase-derived object or an unwrapped native Python function.
requested_results (Sequence[str] or None.) – List of result variables to collect for each toy fit. If None it will default to ('y_pulls', 'parameter_pulls', 'cost').

FIT_TYPE¶: alias of XYFit

AVAILABLE_STATISTICS = {'cor_mat': <property object>, 'cov_mat': <property object>, 'kurtosis': <property object>, 'mean': <property object>, 'mean_error': <property object>, 'skew': <property object>, 'std': <property object>}¶

property n_exp¶

The number of pseudo-experiments to perform.

Return type:: int

property n_par¶

The number of parameters.

Return type:: int

property n_dat¶

The number of data points used for the fit.

Return type:: int

property n_df¶

The number of degrees of freedom for the fit

Return type:: int

add_error(axis, err_val, name=None, correlation=0, relative=False, reference='data')¶

Add an uncertainty source for an axis to the data container.

Parameters:

axis (str or int) – 'x'/0 or 'y'/1
err_val (float or Sequence[float]) – Pointwise uncertainties or a single uncertainty for all data points.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
correlation (float) – Correlation coefficient between any two distinct data points.
relative (bool) – If True, err_val will be interpreted as a relative uncertainty.
reference (str) – Which reference values to use when calculating absolute errors from relative errors. Either 'data' or 'model'.

Returns:

An error id uniquely identifying the created error source.

Return type:

str

add_matrix_error(axis, err_matrix, matrix_type, name=None, err_val=None, relative=False, reference='data')¶

Add a matrix uncertainty source for an axis to the data container.

Parameters:

axis (str or int) – 'x'/0 or 'y'/1
err_matrix (numpy.ndarray) – 2D array of shape (size, size) containing the covariance or correlation matrix
matrix_type (str) – One of 'covariance'/'cov' or 'correlation'/'cor'.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
err_val (Sequence[float]) – The pointwise uncertainties. This is mandatory if only a correlation matrix is given.
relative (bool) – If True, the covariance matrix and/or err_val will be interpreted as a relative uncertainty.
reference (str) – Which reference values to use when calculating absolute errors from relative errors. Either 'data' or 'model'.

Returns:

An error id uniquely identifying the created error source.

Return type:

str

run()¶: Perform the pseudo-experiments. Retrieve and store the requested fit result variables.

get_results(*results)¶

Return a dictionary containing the ensembles of result variables.

Parameters:: results (Iterable[str]) – Names of result variables to retrieve. Calling without arguments retrieves all collected results.
Return type:: dict

get_results_statistics(results='all', statistics='all')¶

Return a dictionary containing statistics (e.g. mean) of the result variables.

Parameters:

results (Iterable[str] or str) – Names of retrieved fit variable for which to return statistics. If 'all', get statistics for all retrieved variables
statistics (Iterable[str] or str) – Names of statistics to retrieve for each result variable. If 'all', get all statistics for each retrieved variable

Return type:

dict

plot_result_distributions(results='all', show_legend=True)¶

Make plots with histograms of the requested fit variable values across all pseudo-experiments.

Parameters:

results (Iterable[str] or str) – Names of retrieved fit variable for which to generate plots. If 'all', plots for all retrieved variables will be made.
show_legend (bool) – If a legend is shown on each figure.

plot_result_scatter(results='all', show_legend=True)¶

Make scatter plots of the requested fit variable values across all pseudo-experiments.

Parameters:

results (Iterable[str] or str) – Names of retrieved fit variable for which to generate plots. If 'all', plots for all retrieved variables will be made.
show_legend (bool) – If a legend is shown on each figure.

AVAILABLE_RESULTS = {'cost': <property object>, 'parameter_pulls': <property object>, 'x_data': <property object>, 'y_data': <property object>, 'y_model': <property object>, 'y_pulls': <property object>}¶

class kafe2.fit.xy.XYParametricModel(x_data, model_func=<function linear_model>, model_parameters=(1.0, 1.0))¶

Bases: ParametricModelBaseMixin, XYContainer

Construct an XYParametricModel object:

Parameters:

x_data (Collection[float]) – 1D array containing the x values supporting the model
model_func (Callable) – Python function handle of the model function.
model_parameters (Collection[float]) – 1D array containing the parameter values with which the model function should be initialized.

property data¶

2D array with shape (2, N) containing the model predictions.

Return type:: numpy.ndarray[numpy.ndarray[float]]

property x¶

1D array containing the x support values.

Return type:: numpy.ndarray[float]

property y¶

1D array containing the y values calculated from the x support values and the current parameters.

Return type:: numpy.ndarray[float]

eval_model_function(x=None, model_parameters=None)¶

Evaluate the model function.

Parameters:

x (numpy.ndarray[float]) – 1D array containing the x values of the support points. If None, the model x values are used.
model_parameters (Collection[float] or None) – 1D array containing the values of the model parameters. If None, the current values are used.

Returns:

Values of the model function for the given parameters.

Return type:

numpy.ndarray[float]

eval_model_function_derivative_by_parameters(x=None, model_parameters=None, par_dx=None)¶

Evaluate the derivative of the model function with respect to the model parameters.

Parameters:

x (numpy.ndarray[float] or None) – 1D array with length N containing the x values of the support points. If None, the model x values are used.
model_parameters (Collection[float] or None) – 1D array with length pars containing the values of the model parameters. If None, the current values are used.
par_dx (Collection[float]) – 1D array with length pars containing the numeric differentiation step size for each parameter.

Returns:

2D array with shape (pars, N) containing the values of the model function derivatives with respect to the parameters.

Return type:

numpy.ndarray[numpy.ndarray[float]]

eval_model_function_derivative_by_x(x=None, model_parameters=None, dx=None)¶

Evaluate the derivative of the model function with respect to the independent variable.

Parameters:

x (numpy.ndarray[float] or None) – 1D array containing the x values of the support points. If None, the model x values are used.
model_parameters (Collection[float] or None) – 1D array containing the values of the model parameters. If None, the current values are used.
dx (float or Collection[float]) – Step size for numeric differentiation.

Returns:

1D array containing the values of the model function derivative for each parameter.

Return type:

numpy.ndarray[float]

class kafe2.fit.xy.XYPlotAdapter(xy_fit_object, from_container=False)¶

Bases: PlotAdapterBase

Construct an XYPlotContainer for a XYFit object:

Parameters:

xy_fit_object (kafe2.XYFit) – The XYFit object handled by this plot adapter.
from_container (bool) – Whether xy_fit_object was created ad-hoc from just a data container.

PLOT_STYLE_CONFIG_DATA_TYPE = 'xy'¶

PLOT_SUBPLOT_TYPES = {'data': {'container_valid': True, 'plot_adapter_method': 'plot_data', 'target_axes': 'main'}, 'model': {'hide': True, 'plot_adapter_method': 'plot_model', 'target_axes': 'main'}, 'model_error_band': {'plot_adapter_method': 'plot_model_error_band', 'target_axes': 'main'}, 'model_line': {'plot_adapter_method': 'plot_model_line', 'target_axes': 'main'}, 'ratio': {'plot_adapter_method': 'plot_ratio', 'plot_style_as': 'data', 'target_axes': 'ratio'}, 'ratio_error_band': {'plot_adapter_method': 'plot_ratio_error_band', 'plot_style_as': 'model_error_band', 'target_axes': 'ratio'}, 'residual': {'plot_adapter_method': 'plot_residual', 'plot_style_as': 'data', 'target_axes': 'residual'}, 'residual_error_band': {'plot_adapter_method': 'plot_residual_error_band', 'plot_style_as': 'model_error_band', 'target_axes': 'residual'}}¶

AVAILABLE_X_SCALES = ('linear', 'log')¶

property data_x¶

The x coordinates of the data (used by plot_data).

Return type:: numpy.ndarray

property data_y¶

The y coordinates of the data (used by plot_data).

Return type:: numpy.ndarray

property data_xerr¶

The magnitude of the data x error bars (used by plot_data).

Return type:: numpy.ndarray

property data_yerr¶

The magnitude of the data y error bars (used by plot_data).

Return type:: numpy.ndarray

property model_x¶

The x coordinates of the model (used by plot_model).

Return type:: numpy.ndarray

property model_y¶

The y coordinates of the model (used by plot_model).

Return type:: numpy.ndarray

property model_xerr¶

The magnitude of the model x error bars (used by plot_model).

Return type:: numpy.ndarray

property model_yerr¶

The magnitude of the model y error bars (used by plot_model).

Return type:: numpy.ndarray

property x_scale¶

The x axis scale. Available scales are given in AVAILABLE_X_SCALES

Return type:: str

property model_line_x¶

x support values for model function. Adapts spacing to x_scale.

Return type:: numpy.ndarray[float]

property model_line_y¶

y values of the model function at the support points model_line_x.

Return type:: numpy.ndarray[float]

property y_error_band¶

1D array representing the uncertainty band around the model function at the support points model_line_x.

Return type:: numpy.ndarray[float]

plot_data(target_axes, error_contributions=('data',), **kwargs)¶

Plot the measurement data to a specified matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
error_contributions (str or Tuple[str]) – Which error contributions to include when plotting the data. Can either be data, 'model' or both.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.errorbar.

Returns:

plot handle(s)

plot_model(target_axes, error_contributions=('model',), **kwargs)¶

Plot the model data to a specified matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
error_contributions (str or Tuple[str] Can either be data, 'model' or both.) – Which error contributions to include when plotting the model.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.errorbar.

Returns:

plot handle(s)

plot_model_line(target_axes, **kwargs)¶

Plot the model function to a specified matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.plot.

Returns:

plot handle(s)

plot_model_error_band(target_axes, **kwargs)¶

Plot an error band around the model model function.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.fill_between.

Returns:

plot handle(s)

plot_ratio_error_band(target_axes, **kwargs)¶

Plot model error band around the data/model ratio to specified matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.fill_between.

Returns:

plot handle(s)

plot_residual_error_band(target_axes, **kwargs)¶

Plot model error band around the data/model ratio to specified matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.fill_between.

Returns:

plot handle(s)

update_plot_kwargs(plot_type, plot_kwargs)¶

Update the value of keyword arguments plot_kwargs to be passed to the plot method for for plot_type.

If a keyword argument should be removed, the value of the keyword in plot_kwargs can be set to the special value '__del__'. To indicate that the default value should be used, the special value '__default__' can be set as a value.

Parameters:

plot_type (str) – key identifying a registered plot type for this PlotAdapter
plot_kwargs (dict) – dictionary containing keywords arguments to override

Tools for Fitting Series of Indexed Measurements: `indexed`¶

This submodule provides the necessary objects for parameter estimation using data consisting of an indexed series of measurements. This can be useful for calculating weighted mean values or template fits.

synopsis:: This submodule provides the necessary objects for parameter estimation using data consisting of an indexed series of measurements.

class kafe2.fit.indexed.IndexedContainer(data, dtype=<class 'float'>)¶

Bases: DataContainerBase

This object is a specialized data container for series of indexed measurements.

Construct a container for indexed data:

Parameters:

data (iterable of type <dtype>) – a one-dimensional array of measurements
dtype (type) – data type of the measurements

property size¶: number of data points

property data¶: container data (one-dimensional numpy.ndarray)

property err¶: absolute total data uncertainties (one-dimensional numpy.ndarray)

property cov_mat¶: absolute data covariance matrix (numpy.matrix)

property cov_mat_inverse¶: inverse of absolute data covariance matrix (numpy.matrix), or None if singular

property cor_mat¶: absolute data correlation matrix (numpy.matrix)

property data_range¶

the minimum and maximum value of the data

Type:: return

add_error(err_val, name=None, correlation=0, relative=False)¶

Add an uncertainty source to the data container. Returns an error id which uniquely identifies the created error source.

Parameters:

err_val (float or iterable of float) – pointwise uncertainty/uncertainties for all data points
name (str or None) – unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
correlation (float) – correlation coefficient between any two distinct data points
relative (bool) – if True, err_val will be interpreted as a relative uncertainty

Returns:

error name

Return type:

str

add_matrix_error(err_matrix, matrix_type, name=None, err_val=None, relative=False)¶

Add a matrix uncertainty source to the data container. Returns an error id which uniquely identifies the created error source.

Parameters:

err_matrix – covariance or correlation matrix
matrix_type (str) – one of 'covariance'/'cov' or 'correlation'/'cor'
name (str or None) – unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
err_val (iterable of float) – the pointwise uncertainties (mandatory if only a correlation matrix is given)
relative (bool) – if True, the covariance matrix and/or err_val will be interpreted as a relative uncertainty

Returns:

error name

Return type:

str

class kafe2.fit.indexed.IndexedCostFunction(cost_function, arg_names=None, add_constraint_cost=True, add_determinant_cost=False)¶

Bases: CostFunction

Construct CostFunction object (a wrapper for a native Python function):

Parameters:

cost_function (Callable) – function handle
arg_names (Iterable[str]) – the names to use for the cost function arguments. If None, detect from function signature.
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.indexed.IndexedCostFunction_Chi2(errors_to_use='covariance', fallback_on_singular=True, add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction_Chi2

Base class for built-in least-squares cost function.

Parameters:

errors_to_use (str or None) – Which errors to use when calculating $\chi^2$ . Either 'covariance', 'pointwise' or None.
fallback_on_singular (bool) – If True and the covariance matrix is singular (or the errors are zero), calculate $\chi^2$ as with errors_to_use=None
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.indexed.IndexedCostFunction_GaussApproximation(errors_to_use='covariance', add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction_GaussApproximation

Base class for built-in Gaussian approximation of the Poisson negative log-likelihood cost function.

Parameters:

errors_to_use (str) – Which errors to use when calculating $\chi^2$ . Either 'covariance', 'pointwise'.
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.indexed.IndexedCostFunction_NegLogLikelihood(data_point_distribution='poisson', ratio=False)¶

Bases: CostFunction_NegLogLikelihood

Base class for built-in negative log-likelihood cost function.

In general, a negative log-likelihood cost function is defined as the double negative logarithm of the product of the individual likelihoods of the data points.

The likelihood ratio is defined as ratio of the likelihood function for each individual observation, divided by the so-called marginal likelihood.

Parameters:

data_point_distribution (str) – Which type of statistics to use for modelling the distribution of individual data points. Either 'poisson' or 'gaussian'.
ratio (bool) – If True, divide the likelihood by the marginal likelihood.

class kafe2.fit.indexed.IndexedFit(data, model_function, cost_function='chi2', minimizer=None, minimizer_kwargs=None, dynamic_error_algorithm='nonlinear')¶

Bases: FitBase

Construct a fit of a model to a series of indexed measurements.

Parameters:

data (iterable of float) – the measurement values
model_function (IndexedModelFunction or unwrapped native Python function) – the model function
cost_function (CostFunctionBase-derived or unwrapped native Python function) – the cost function
minimizer (None, "iminuit", "tminuit", or "scipy".) – the minimizer to use for fitting.
minimizer_kwargs (dict) – dictionary with kwargs for the minimizer.

CONTAINER_TYPE¶: alias of IndexedContainer

MODEL_TYPE¶: alias of IndexedParametricModel

MODEL_FUNCTION_TYPE¶: alias of IndexedModelFunction

PLOT_ADAPTER_TYPE¶: alias of IndexedPlotAdapter

RESERVED_NODE_NAMES = {'cost', 'data', 'data_cor_mat', 'data_cov_mat', 'data_error', 'model', 'model_cor_mat', 'model_cov_mat', 'model_error', 'total_cor_mat', 'total_cov_mat', 'total_error'}¶

property model¶: array of model predictions for the data points

class kafe2.fit.indexed.IndexedModelFunction(model_function)¶

Bases: ModelFunctionBase

Construct IndexedModelFunction object (a wrapper for a native Python function):

Parameters:: model_function – function handle

FORMATTER_TYPE¶: alias of IndexedModelFunctionFormatter

class kafe2.fit.indexed.IndexedModelFunctionFormatter(name, latex_name=None, index_name='i', latex_index_name='i', arg_formatters=None, expression_string=None, latex_expression_string=None)¶

Bases: FunctionFormatter

Construct a Formatter for a model function for indexed data:

Parameters:

name – a plain-text-formatted string indicating the function name
latex_name – a LaTeX-formatted string indicating the function name
index_name – a plain-text-formatted string representing the index
latex_index_name – a LaTeX-formatted string representing the index
arg_formatters – list of ParameterFormatter-derived objects, formatters for function arguments
expression_string – a plain-text-formatted string indicating the function expression
latex_expression_string – a LaTeX-formatted string indicating the function expression

property index_name¶

The parameter name of the index.

Return type:: str

property latex_index_name¶

The LaTeX parameter name of the index.

Return type:: str

get_formatted(with_par_values=False, n_significant_digits=2, format_as_latex=False, with_expression=False)¶

Get a formatted string representing this model function.

Parameters:

with_par_values – if True, output will include the value of each function parameter (e.g. f_i(a=1, b=2, ...))
n_significant_digits (int) – number of significant digits for rounding
format_as_latex – if True, the returned string will be formatted using LaTeX syntax
with_expression – if True, the returned string will include the expression assigned to the function

Returns:

string

class kafe2.fit.indexed.IndexedParametricModel(model_func, model_parameters, shape_like=None)¶

Bases: ParametricModelBaseMixin, IndexedContainer

Construct an IndexedParametricModel object:

Parameters:

model_func – handle of Python function (the model function)
model_parameters – iterable of parameter values with which the model function should be initialized
shape_like – array with the same shape as the model

MODEL_FUNCTION_TYPE¶: alias of IndexedModelFunction

property data¶: model predictions (one-dimensional numpy.ndarray)

property data_range¶: tuple containing the minimum and maximum of all model predictions

eval_model_function(model_parameters=None)¶

Evaluate the model function.

Parameters:: model_parameters (list or None) – values of the model parameters (if None, the current values are used)
Returns:: value(s) of the model function for the given parameters
Return type:: numpy.ndarray

eval_model_function_derivative_by_parameters(model_parameters=None, par_dx=None)¶

Evaluate the derivative of the model function with respect to the model parameters.

Parameters:

model_parameters (list or None) – values of the model parameters (if None, the current values are used)
par_dx (float) – step size for numeric differentiation

Returns:

value(s) of the model function derivative for the given parameters

Return type:

numpy.ndarray

class kafe2.fit.indexed.IndexedPlotAdapter(indexed_fit_object, from_container=False)¶

Bases: PlotAdapterBase

Construct an IndexedPlotContainer for a IndexedFit object:

Parameters:

fit_object – an IndexedFit object
from_container (bool) – Whether indexed_fit_object was created ad-hoc from just a data container.

PLOT_STYLE_CONFIG_DATA_TYPE = 'indexed'¶

PLOT_SUBPLOT_TYPES = {'data': {'container_valid': True, 'plot_adapter_method': 'plot_data', 'target_axes': 'main'}, 'model': {'hide': True, 'plot_adapter_method': 'plot_model', 'target_axes': 'main'}, 'ratio': {'plot_adapter_method': 'plot_ratio', 'plot_style_as': 'data', 'target_axes': 'ratio'}, 'residual': {'plot_adapter_method': 'plot_residual', 'plot_style_as': 'data', 'target_axes': 'residual'}}¶

property data_x¶: data x values

property data_y¶: data y values

property data_xerr¶

None for IndexedPlotContainer

Type:: x error bars for data

property data_yerr¶

total uncertainty

Type:: y error bars for data

property model_x¶: model prediction x values

property model_y¶: model prediction y values

property model_xerr¶: x error bars for model (actually used to represent the horizontal step length)

property model_yerr¶

None for IndexedPlotContainer

Type:: y error bars for model

plot_data(target_axes, **kwargs)¶

Plot the measurement data to a specified matplotlib Axes object.

Parameters:

target_axes – matplotlib Axes object
kwargs – keyword arguments accepted by the matplotlib methods errorbar or plot

Returns:

plot handle(s)

plot_model(target_axes, **kwargs)¶

Plot the model predictions to a specified matplotlib Axes object.

Parameters:

target_axes – matplotlib Axes object
kwargs – keyword arguments accepted by the step_fill_between method

Returns:

plot handle(s)

Tools for Fitting Histograms: `histogram`¶

This submodule provides the necessary objects for parameter estimation from histograms. Currently a histogram needs to be filled with all individual data points. A function for setting the bin heights is available but not recommended, as saving and loading those to and from a file is not yet supported.

synopsis:: This submodule provides the necessary objects for parameter estimation from histograms.

class kafe2.fit.histogram.HistContainer(n_bins=None, bin_range=None, bin_edges=None, fill_data=None, dtype=<class 'int'>)¶

Bases: IndexedContainer

This object is a specialized data container for organizing data into histograms.

A histogram is a compact representation of a potentially large number of entries which are distributed along a continuum of values. Histograms divide the continuum into intervals (“bins”) and count the number of entries per interval.

Construct a histogram:

Parameters:

n_bins (int) – how many bins raw data should be split into.
bin_range (iterable[float] of length 2) – the lower and upper bound for the bins specified by n_bins.
bin_edges (iterable[float]) – explicit bin edges for raw data. If None, each bin will have the same width.
fill_data (iterable[float]) – entries to fill into the histogram
dtype (type) – data type of histogram entries

property size¶: the number of bins (excluding underflow and overflow bins)

property n_entries¶: the number of entries

property data¶: the number of entries in each bin

property raw_data¶: the number of entries in each bin

property low¶: the lower edge of the histogram

property high¶: the upper edge of the histogram

property bin_range¶: a tuple containing the lower and upper edges of the histogram

property overflow¶: the number of entries in the overflow bin

property underflow¶: the number of entries in the underflow bin

property n_bins¶: the number of bins

property bin_edges¶: a list of the bin edges (including the outermost ones)

property bin_widths¶: a list of the bin widths

property bin_centers¶: a list of the (geometrical) bin centers

fill(entries)¶

Fill new entries into the histogram.

Parameters:: entries (list of floats) – list of entries

rebin(new_bin_edges)¶

Change the histogram binning.

Parameters:: new_bin_edges (list of float) – list of new bin edges in ascending order

set_bins(bin_heights, underflow=0, overflow=0)¶: Set the bin heights according to a pre-calculated histogram :param bin_heights: Heights of the bins :type bin_heights: list of int :param underflow: Number of entries in the underflow bin :type underflow: int :param overflow: Number of entries in the overflow bin :type overflow: int

class kafe2.fit.histogram.HistCostFunction(cost_function, arg_names=None, add_constraint_cost=True, add_determinant_cost=False)¶

Bases: CostFunction

Construct CostFunction object (a wrapper for a native Python function):

Parameters:

cost_function (Callable) – function handle
arg_names (Iterable[str]) – the names to use for the cost function arguments. If None, detect from function signature.
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.histogram.HistCostFunction_Chi2(errors_to_use='covariance', fallback_on_singular=True, add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction_Chi2

Base class for built-in least-squares cost function.

Parameters:

errors_to_use (str or None) – Which errors to use when calculating $\chi^2$ . Either 'covariance', 'pointwise' or None.
fallback_on_singular (bool) – If True and the covariance matrix is singular (or the errors are zero), calculate $\chi^2$ as with errors_to_use=None
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.histogram.HistCostFunction_GaussApproximation(errors_to_use='covariance', add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction_GaussApproximation

Base class for built-in Gaussian approximation of the Poisson negative log-likelihood cost function.

Parameters:

errors_to_use (str) – Which errors to use when calculating $\chi^2$ . Either 'covariance', 'pointwise'.
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

class kafe2.fit.histogram.HistCostFunction_NegLogLikelihood(data_point_distribution='poisson', ratio=False)¶

Bases: CostFunction_NegLogLikelihood

Base class for built-in negative log-likelihood cost function.

In general, a negative log-likelihood cost function is defined as the double negative logarithm of the product of the individual likelihoods of the data points.

The likelihood ratio is defined as ratio of the likelihood function for each individual observation, divided by the so-called marginal likelihood.

Parameters:

data_point_distribution (str) – Which type of statistics to use for modelling the distribution of individual data points. Either 'poisson' or 'gaussian'.
ratio (bool) – If True, divide the likelihood by the marginal likelihood.

class kafe2.fit.histogram.HistFit(data, model_function=<function normal_distribution>, cost_function=<kafe2.fit._base.cost.CostFunction_NegLogLikelihood object>, bin_evaluation='simpson', density=True, minimizer=None, minimizer_kwargs=None, dynamic_error_algorithm='nonlinear')¶

Bases: FitBase

Construct a fit of a model to a histogram. If bin_evaluation is a Python function or of a numpy.vectorize object it is interpreted as the antiderivative of model_density_function. If bin_evaluation is equal to “rectangle”, “midpoint”, “trapezoid”, or “simpson” the bin heights are evaluated according to the corresponding quadrature formula. If bin_evaluation is equal to “numerical” the bin heights are evaluated by numerically integrating model_density_function.

Parameters:

data (HistContainer or two-dimensional iterable of bin heights and bin edges as returned by np.histogram.) – an encapsulated representation of the histogrammed data.
model_function – the model (density) function
cost_function (CostFunctionBase-derived or unwrapped native Python function) – the cost function
bin_evaluation (str, callable, or numpy.vectorize) – how the model evaluates bin heights.
density (bool) – if True, scale model function to the number of data points.
minimizer (None, "iminuit", "tminuit", or "scipy".) – the minimizer to use for fitting.
minimizer_kwargs (dict) – dictionary with kwargs for the minimizer.

CONTAINER_TYPE¶: alias of HistContainer

MODEL_TYPE¶: alias of HistParametricModel

MODEL_FUNCTION_TYPE¶: alias of HistModelFunction

PLOT_ADAPTER_TYPE¶: alias of HistPlotAdapter

RESERVED_NODE_NAMES = {'cost', 'data', 'data_cor_mat', 'data_cov_mat', 'data_error', 'model', 'model_cor_mat', 'model_cov_mat', 'model_density', 'model_error', 'total_cor_mat', 'total_cov_mat', 'total_error'}¶

property model¶: array of model predictions for the data points

property density¶

eval_model_function_density(x, model_parameters=None)¶

Evaluate the model function density.

Parameters:

x (iterable of float) – values of x at which to evaluate the model function density
model_parameters (iterable of float) – the model parameter values (if None, the current values are used)

Returns:

model function density values

Return type:

numpy.ndarray

class kafe2.fit.histogram.HistModelFunction(model_function=None)¶

Bases: ModelFunctionBase

Construct XYModelFunction object (a wrapper for a native Python function):

Parameters:: model_function – function handle

class kafe2.fit.histogram.HistParametricModel(n_bins, bin_range, model_density_func=<function normal_distribution>, model_parameters=[1.0, 1.0], bin_edges=None, bin_evaluation='simpson', density=True)¶

Bases: ParametricModelBaseMixin, HistContainer

Mixin constructor: sets and initialized the model function.

Parameters:

model_func – handle of Python function (the model function)
model_parameters – iterable of parameter values with which the model function should be initialized

MODEL_FUNCTION_TYPE¶: alias of HistModelFunction

property data¶: model predictions (one-dimensional numpy.ndarray)

property bin_evaluation¶

how the model evaluates bin heights. :rtype str, callable, or numpy.vectorize

Type:: return

property bin_evaluation_string¶

string representation of how the model evaluates bin heights. :rtype str

Type:: return

property density¶

eval_model_function_density(x, model_parameters=None)¶

Evaluate the model function density.

Parameters:

x (list of float) – x values of the support points
model_parameters (list or None) – values of the model parameters (if None, the current values are used)

Returns:

value(s) of the model function for the given parameters

Return type:

numpy.ndarray

fill(entries)¶

Fill new entries into the histogram.

Parameters:: entries (list of floats) – list of entries

class kafe2.fit.histogram.HistPlotAdapter(hist_fit_object, from_container=False)¶

Bases: PlotAdapterBase

Construct an HistPlotContainer for a HistFit object:

Parameters:

fit_object – an HistFit object
n_plot_points_model_density – number of plot points to use for plotting the model density
from_container (bool) – Whether hist_fit_object was created ad-hoc from just a data container.

PLOT_STYLE_CONFIG_DATA_TYPE = 'histogram'¶

PLOT_SUBPLOT_TYPES = {'data': {'container_valid': True, 'plot_adapter_method': 'plot_data', 'target_axes': 'main'}, 'model': {'hide': True, 'plot_adapter_method': 'plot_model', 'target_axes': 'main'}, 'model_density': {'plot_adapter_method': 'plot_model_density', 'target_axes': 'main'}, 'ratio': {'plot_adapter_method': 'plot_ratio', 'plot_style_as': 'data', 'target_axes': 'ratio'}, 'residual': {'plot_adapter_method': 'plot_residual', 'plot_style_as': 'data', 'target_axes': 'residual'}}¶

AVAILABLE_X_SCALES = ('linear', 'log')¶

property data_x¶: data x values

property data_y¶: data y values

property data_xerr¶: x error bars for data (actually used to represent the bins)

property data_yerr¶

total uncertainty

Type:: y error bars for data

property model_x¶: model prediction x values

property model_y¶: model prediction y values

property model_xerr¶: x error bars for model (actually used to represent the bins)

property model_yerr¶

None for HistPlotContainer

Type:: y error bars for model

property model_density_x¶: x support points for model density plot

property model_density_y¶: value of model density at the support points

plot_data(target_axes, **kwargs)¶

Plot the measurement data to a specified matplotlib Axes object.

Parameters:

target_axes – matplotlib Axes object
kwargs – keyword arguments accepted by the matplotlib method errorbar

Returns:

plot handle(s)

plot_model(target_axes, **kwargs)¶

Plot the model predictions to a specified matplotlib Axes object.

Parameters:

target_axes – matplotlib Axes object
kwargs – keyword arguments accepted by the matplotlib method bar

Returns:

plot handle(s)

plot_model_density(target_axes, **kwargs)¶

Plot the model density to a specified matplotlib Axes object.

Parameters:

target_axes – matplotlib Axes object
kwargs – keyword arguments accepted by the matplotlib method plot

Returns:

plot handle(s)

Abstract Base Classes: `_base`¶

synopsis:: This submodule contains the abstract base classes for all objects used by the kafe2.fit module.

class kafe2.fit._base.CostFunction(cost_function, arg_names=None, add_constraint_cost=True, add_determinant_cost=False)¶

Bases: FileIOMixin, object

Base class for cost functions. Built from a Python function with some extra functionality used by Fit objects.

Any Python function returning a float can be used as a cost function, although a number of common cost functions are provided as built-ins for all fit types.

In order to be used as a model function, a native Python function must be wrapped by an object whose class derives from this base class. There is a dedicated CostFunction specialization for each type of fit.

This class provides the basic functionality used by all CostFunction objects. These use introspection (inspect) for determining the parameter structure of the cost function and to ensure the function can be used as a cost function (validation).

Construct CostFunction object (a wrapper for a native Python function):

Parameters:

cost_function (Callable) – function handle
arg_names (Iterable[str]) – the names to use for the cost function arguments. If None, detect from function signature.
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

property name¶: The cost function name (a valid Python identifier)

property func¶: The cost function handle

property arg_names¶: The names of the cost function arguments.

property formatter¶: The Formatter object for this function

property argument_formatters¶: The Formatter objects for the function arguments

property needs_errors¶: Whether the cost function needs errors for a meaningful result

property is_chi2¶: Whether the cost function is a chi2 cost function.

property saturated¶: Whether the cost function value is calculated from a saturated likelihood.

property add_determinant_cost¶: Whether the determinant cost is being added automatically to the cost function value.

property kafe2go_identifier¶: Short string representation (if any) of this cost function when dumping to file.

property pointwise¶: True if cost function result does not depend on covariances.

property pointwise_version¶: Optimized version of cost function that uses pointwise errors, can be None.

property errors_valid¶

goodness_of_fit(*args)¶: How well the model agrees with the data.

chi2_probability(cost_function_value, ndf)¶

The chi2 probability associated with this cost function, None for non-chi2 cost functions.

Parameters:

cost_function_value (float) – the associated cost function value.
ndf (int) – the associated number of degrees of freedom.

Returns:

the associated chi2 probability.

Return type:

float or None

get_uncertainty_gaussian_approximation(data)¶

Get the gaussian approximation of the uncertainty inherent to the cost function, returns 0 by default.

Parameters:: data – the fit data
Returns:: the approximated gaussian uncertainty given the fit data

is_data_compatible(data)¶

Tests if model data is compatible with cost function

Parameters:: data (numpy.ndarray) – the fit data
Returns:: if the data is compatible, and if not a reason for the incompatibility
Return type:: (boo, str)

class kafe2.fit._base.CostFunctionFormatter(name, name_saturated=None, latex_name=None, latex_name_saturated=None, arg_formatters=None, expression_string=None, latex_expression_string=None)¶

Bases: FunctionFormatter

A Formatter class for Cost Functions.

Construct a formatter for a model function:

Parameters:

name (str) – A plain-text-formatted string indicating the function name.
latex_name (str) – A LaTeX-formatted string indicating the function name.
arg_formatters (list[kafe2.fit._base.ParameterFormatter]) – List of ParameterFormatter-derived objects, formatters for function arguments.
expression_string (str) – A plain-text-formatted string indicating the function expression.
latex_expression_string (str) – A LaTeX-formatted string indicating the function expression.

property name_saturated¶

A plain-text-formatted string indicating the saturated function name.

Return type:: str

property latex_name_saturated¶

A LaTeX-formatted string indicating the saturated function name.

Return type:: str

get_formatted(value=None, n_degrees_of_freedom=None, with_name=True, saturated=False, with_value_per_ndf=True, format_as_latex=False)¶

Get a formatted string representing this cost function.

Parameters:

value (float or None) – Value of the cost function (if not None, the returned string will include this).
n_degrees_of_freedom (int or None) – Number of degrees of freedom (if not None, the returned string will include this).
with_name (bool) – If True, the returned string will include the cost function name
saturated (bool) – If True, the cost function name for the saturated Likelihood will be used (no effect for chi2).
with_value_per_ndf (bool) – If True, the returned string will include the value-ndf ratio as a decimal value
format_as_latex (bool) – If True, the returned string will be formatted using LaTeX syntax

Return type:

str

class kafe2.fit._base.CostFunction_Chi2(errors_to_use='covariance', fallback_on_singular=True, add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction

Base class for built-in least-squares cost function.

Parameters:

errors_to_use (str or None) – Which errors to use when calculating $\chi^2$ . Either 'covariance', 'pointwise' or None.
fallback_on_singular (bool) – If True and the covariance matrix is singular (or the errors are zero), calculate $\chi^2$ as with errors_to_use=None
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

chi2_no_errors(data, model)¶

A least-squares cost function calculated from (y) data and model values, without considering uncertainties:

$C = \chi^2({\bf d}, {\bf m}) = \sum_k (d_k - m_k)^2 + C_{\rm con}({\bf p}).$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, and $C_{\rm con}({\bf p})$ is the additional cost resulting from any constrained parameters.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$

Returns:

cost function value

chi2_covariance(data, model, total_cov_mat_cholesky)¶

A least-squares cost function calculated from (y) data and model values, considering the covariance matrix of the (y) measurements. The cost function value can be calculated as follows:

$C = \chi^2({\bf d}, {\bf m}) = ({\bf d} - {\bf m})^{\top}\,{{\bf V}^{-1}}\,({\bf d} - {\bf m}) + C_{\rm con}({\bf p}) + C_{\rm det}({\bf V}).$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, ${{\bf V}^{-1}}$ is the inverse of the total covariance matrix, $C_{\rm con}({\bf p})$ is the additional cost resulting from any constrained parameters, and $C_{\rm det}({\bf V}) = \ln \det({\bf V})$ is the additional cost to compensate for a non-constant covariance matrix.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$
total_cov_mat_cholesky – Cholesky decomposition of the total covariance matrix ${\bf L}$ with ${\bf L}^\top {\bf L} = {\bf V}$

Returns:

cost function value

chi2_pointwise_errors(data, model, total_error)¶

A least-squares cost function calculated from (y) data and model values, considering pointwise (uncorrelated) uncertainties for each data point:

$C = \chi^2({\bf d}, {\bf m}, {\bf \sigma}) = \sum_k \frac{d_k - m_k}{\sigma_k} + C_{\rm con}({\bf p}) + C_{\rm det}({\bf \sigma}).$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, ${\bf \sigma}$ are the pointwise total uncertainties, $C_{\rm con}({\bf p})$ is the additional cost resulting from any constrained parameters, and $C_{\rm det}({\bf \sigma}) = \ln \prod_k \sigma_k^2$ is the additional cost to compensate for non-constant errors.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$
total_error – total error vector ${\bf \sigma}$

Returns:

cost function value

property pointwise¶: True if cost function result does not depend on covariances.

property pointwise_version¶: Optimized version of cost function that uses pointwise errors, can be None.

class kafe2.fit._base.CostFunction_GaussApproximation(errors_to_use='covariance', add_constraint_cost=True, add_determinant_cost=True)¶

Bases: CostFunction

Base class for built-in Gaussian approximation of the Poisson negative log-likelihood cost function.

Parameters:

errors_to_use (str) – Which errors to use when calculating $\chi^2$ . Either 'covariance', 'pointwise'.
add_constraint_cost (bool) – If True, automatically add the cost for kafe2 constraints.
add_determinant_cost (bool) – If True, automatically increase the cost function value by the logarithm of the determinant of the covariance matrix to reduce bias.

gaussian_approximation_covariance(data, model, total_cov_mat)¶

A least-squares cost function calculated from (y) data and model values, considering the covariance matrix of the (y) measurements. The cost function value can be calculated as follows:

$C = \chi^2({\bf d}, {\bf m}, {\bf V}) = ({\bf d} - {\bf m})^{\top}\,{\tilde{\bf V}^{-1}}\,({\bf d} - {\bf m}) + C_{\rm con}({\bf p}) + C_{\rm det}(\tilde{\bf V}); \quad \tilde{{\bf V}}_{ij} = {\bf V}_{ij} + \delta_{ij} {\bf m}_i.$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, ${{\bf V}^{-1}}$ is the inverse of the total covariance matrix, $C_{\rm con}({\bf p})$ is the additional cost resulting from any constrained parameters, and $C_{\rm det}(\tilde{\bf V}) = \ln \det(\tilde{\bf V})$ is the additional cost to compensate for a non-constant covariance matrix.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$
total_cov_mat – The total covariance matrix ${\bf V}$

Returns:

cost function value

gaussian_approximation_pointwise_errors(data, model, total_error)¶

A least-squares cost function calculated from data and model values, considering pointwise (uncorrelated) uncertainties for each data point:

$C = \chi^2({\bf d}, {\bf m}, {\bf \sigma}) = \sum_k \left( \frac{d_k - m_k}{\sigma_k + \sqrt{m_k}} \right)^2 + C_{\rm con}({\bf p}) + C_{\rm det}({\bf \sigma}).$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, ${\bf \sigma}$ are the pointwise total uncertainties, $C({\bf p})$ is the additional cost resulting from any constrained parameters, and $C_{\rm det}({\bf \sigma}) = \ln \prod_k m_k + \sigma_k^2$ is the additional cost to compensate for non-constant errors.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$
total_error – total error vector ${\bf \sigma}$

Returns:

cost function value

property pointwise¶: True if cost function result does not depend on covariances.

property pointwise_version¶: Optimized version of cost function that uses pointwise errors, can be None.

goodness_of_fit(*args)¶: How well the model agrees with the data.

get_uncertainty_gaussian_approximation(data)¶

Get the gaussian approximation of the uncertainty inherent to the cost function, returns 0 by default.

Parameters:: data – the fit data
Returns:: the approximated gaussian uncertainty given the fit data

class kafe2.fit._base.CostFunction_NegLogLikelihood(data_point_distribution='poisson', ratio=False)¶

Bases: CostFunction

Base class for built-in negative log-likelihood cost function.

In general, a negative log-likelihood cost function is defined as the double negative logarithm of the product of the individual likelihoods of the data points.

The likelihood ratio is defined as ratio of the likelihood function for each individual observation, divided by the so-called marginal likelihood.

Parameters:

data_point_distribution (str) – Which type of statistics to use for modelling the distribution of individual data points. Either 'poisson' or 'gaussian'.
ratio (bool) – If True, divide the likelihood by the marginal likelihood.

static nll_gaussian(data, model, total_error)¶

A negative log-likelihood function assuming Gaussian statistics for each measurement.

The cost function is given by:

$C = -2 \ln \mathcal{L}({\bf d}, {\bf m}, {\bf \sigma}) = -2 \ln \prod_j \mathcal{L}_{\rm Gaussian} (x=d_j, \mu=m_j, \sigma=\sigma_j) + C_{\rm con}({\bf p}).$

$\rightarrow C = -2 \ln \prod_j \frac{1}{\sqrt{2{\sigma_j}^2\pi}} \exp{\left(-\frac{ (d_j-m_j)^2 }{ {\sigma_j}^2}\right)} + C_{\rm con}({\bf p}).$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, ${\bf \sigma}$ are the pointwise total uncertainties, and $C_{\rm con}({\bf p})$ is the additional cost resulting from any constrained parameters.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$
total_error – total error vector ${\bf \sigma}$

Returns:

cost function value

static nll_poisson(data, model)¶

A negative log-likelihood function assuming Poisson statistics for each measurement.

The cost function is given by:

$C = -2 \ln \mathcal{L}({\bf d}, {\bf m}) = -2 \ln \prod_j \mathcal{L}_{\rm Poisson} (k=d_j, \lambda=m_j) + C_{\rm con}({\bf p}).$

$\rightarrow C = -2 \ln \prod_j \frac{{m_j}^{d_j} \exp(-m_j)}{d_j!} + C_{\rm con}({\bf p}).$

In the above, ${\bf d}$ are the measurements, ${\bf m}$ are the model predictions, and $C_{\rm con}({\bf p})$ is the additional cost resulting from any constrained parameters.

Parameters:

data – measurement data ${\bf d}$
model – model predictions ${\bf m}$

Returns:

cost function value

static nllr_gaussian(data, model, total_error)¶

static nllr_poisson(data, model)¶

is_data_compatible(data)¶

Tests if model data is compatible with cost function

Parameters:: data (numpy.ndarray) – the fit data
Returns:: if the data is compatible, and if not a reason for the incompatibility
Return type:: (boo, str)

get_uncertainty_gaussian_approximation(data)¶

Get the gaussian approximation of the uncertainty inherent to the cost function, returns 0 by default.

Parameters:: data – the fit data
Returns:: the approximated gaussian uncertainty given the fit data

class kafe2.fit._base.DataContainerBase¶

Bases: FileIOMixin

This is a purely abstract class implementing the minimal interface required by all types of data containers.

It stores measurement data and uncertainties.

property label¶

The label describing the dataset.

Return type:: str or None

property axis_labels¶

The axis labels describing the dataset.

Return type:: tuple[str or None, str or None]

property x_label¶

The x-axis label.

Return type:: str or None

property y_label¶

The y-axis label.

Return type:: str or None

abstract property size¶

The size of the data (number of measurement points).

Return type:: int

abstract property data¶

A numpy array containing the data values.

Return type:: numpy.ndarray[float]

abstract property err¶

A numpy array containing the pointwise data uncertainties.

Return type:: numpy.ndarray[float]

abstract property cov_mat¶

A numpy matrix containing the covariance matrix of the data.

Return type:: numpy.ndarray[numpy.ndarray[float]]

abstract property cov_mat_inverse¶

obj`None` if not invertible).

Return type:: numpy.ndarray[numpy.ndarray[float]] or None
Type:: A numpy matrix containing inverse of the data covariance matrix (or
Type:: py

property has_errors¶

True if at least one uncertainty source is defined for the data container.

Return type:: bool

add_error(err_val, name=None, correlation=0, relative=False, reference=None)¶

Add an uncertainty source to the data container.

Parameters:

err_val (float or numpy.ndarray[float]) – Pointwise uncertainty/uncertainties for all data points.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
correlation (float) – Correlation coefficient between any two distinct data points.
relative (bool) – If True, err_val will be interpreted as a relative uncertainty.
reference (Iterable[float] or None) – The data values to use when computing absolute errors from relative ones (and vice-versa)

Returns:

An error id which uniquely identifies the created error source.

Return type:

str

add_matrix_error(err_matrix, matrix_type, name=None, err_val=None, relative=False, reference=None)¶

Add a matrix uncertainty source to the data container.

Parameters:

err_matrix – Covariance or correlation matrix.
matrix_type (str) – One of 'covariance'/'cov' or 'correlation'/'cor'.
name (str or None) – Unique name for this uncertainty source. If :py:obj`None`, the name of the error source will be set to a random alphanumeric string.
err_val (Iterable[float]) – The pointwise uncertainties (mandatory if only a correlation matrix is given).
relative (bool) – If True, the covariance matrix and/or err_val will be interpreted as a relative uncertainty.
reference (Iterable[float] or None) – the data values to use when computing absolute errors from relative ones (and vice-versa)

Returns:

An error id which uniquely identifies the created error source.

Return type:

str

disable_error(error_name)¶

Temporarily disable an uncertainty source so that it doesn’t count towards calculating the total uncertainty.

Parameters:: error_name (str) – error name

enable_error(error_name)¶

(Re-)Enable an uncertainty source so that it counts towards calculating the total uncertainty.

Parameters:: error_name (str) – error name

get_matching_errors(matching_criteria=None, matching_type='equal')¶

Return a list of uncertainty objects fulfilling the specified matching criteria.

Valid keys for matching_criteria:

name (the unique error name)
type (either simple or matrix)
correlated (bool, only matches simple errors!)
relative (bool)

Note

The error objects contained in the dictionary are not copies, but the original error objects. Modifying them is possible, but not recommended. If you do modify any of them, the changes will not be reflected in the total error calculation until the error cache is cleared. This can be done by calling the private method _clear_total_error_cache.

Parameters:

matching_criteria (dict or None) – Key-value pairs specifying matching criteria. The resulting error array will only contain error objects matching all provided criteria. If None, all error objects are returned.
matching_type (str) – How to perform the matching. If 'equal', the value in matching_criteria is checked for equality against the stored value. If 'regex', the value in matching_criteria is interpreted as a regular expression and is matched against the stored value.

Returns:

Dict mapping error name to GaussianErrorBase-derived error objects.

Return type:

dict[str, kafe2.core.error.GaussianErrorBase]

get_error(error_name)¶

Return the uncertainty object holding the uncertainty.

Note

If you modify this object, the changes will not be reflected in the total error calculation until the error cache is cleared. This can be forced by calling enable_error.

Parameters:: error_name (str) – error name
Returns:: error object
Return type:: kafe2.core.error.GaussianErrorBase

get_total_error()¶

Get the error object representing the total uncertainty.

Returns:: error object representing the total uncertainty
Return type:: kafe2.core.error.MatrixGaussianError

class kafe2.fit._base.FitBase(data, model_function, cost_function, minimizer=None, minimizer_kwargs=None, dynamic_error_algorithm='nonlinear')¶

Bases: FileIOMixin, object

This is a purely abstract class implementing the minimal interface required by all types of fitters.

This is a purely abstract class implementing the minimal interface required by all types of fits.

Parameters:

minimizer (str or None) – Name of the minimizer to use.
minimizer_kwargs (dict or None) – Dictionary wit keywords for initializing the minimizer.
dynamic_error_algorithm ("nonlinear" or "iterative".) – how to handle errors that depend on the model parameters.

CONTAINER_TYPE¶: alias of DataContainerBase

MODEL_TYPE = None¶

MODEL_FUNCTION_TYPE = None¶

PLOT_ADAPTER_TYPE = None¶

RESERVED_NODE_NAMES = {}¶

property data¶: array of measurement values

property data_error¶: array of pointwise data uncertainties

property data_cov_mat¶: the data covariance matrix

property data_cov_mat_inverse¶: inverse of the data covariance matrix (or None if singular)

property data_cor_mat¶: the data correlation matrix

property data_container¶

The data container used in this fit.

Return type:: kafe2.fit._base.DataContainerBase

abstract property model¶

property model_error¶: array of pointwise model uncertainties

property model_cov_mat¶: the model covariance matrix

property model_cov_mat_inverse¶: inverse of the model covariance matrix (or None if singular)

property model_cor_mat¶: the model correlation matrix

property total_error¶: array of pointwise total uncertainties

property total_cov_mat¶: the total covariance matrix

property total_cov_mat_inverse¶: inverse of the total covariance matrix (or None if singular)

property total_cor_mat¶: the total correlation matrix

property model_function¶

The wrapped model function as a ModelFunctionBase or derived object. This object contains the model function as well as formatting information used for this fit.

Return type:: kafe2.fit._base.ModelFunctionBase

property model_label¶

The label of the model used in this fit.

Return type:: str or None

property parameter_values¶

The current parameter values.

Return type:: numpy.ndarray[float]

property parameter_names¶

The current parameter names.

Return type:: tuple[str]

property parameter_errors¶

The current parameter uncertainties. Can be set to control initial step size during minimization.

Return type:: numpy.ndarray[float]

property parameter_cov_mat¶

The current parameter covariance matrix.

Return type:: None or numpy.ndarray[numpy.ndarray[float]]

property parameter_cor_mat¶

The current parameter correlation matrix.

Return type:: None or numpy.ndarray[numpy.ndarray[float]]

property asymmetric_parameter_errors¶

The current asymmetric parameter uncertainties.

Return type:: numpy.ndarray[numpy.ndarray[float, float]]

property parameter_name_value_dict¶

A dictionary mapping each parameter name to its current value.

Return type:: OrderedDict[str, float]

property parameter_constraints¶

The gaussian constraints given for the fit parameters.

Return type:: list[kafe2.core.constraint.GaussianSimpleParameterConstraint or kafe2.core.constraint.GaussianMatrixParameterConstraint]

property cost_function_value¶

The current value of the cost function.

Return type:: float

property data_size¶

The size (number of points) of the data container.

Return type:: int

property has_model_errors¶

True if at least one uncertainty source is defined for the model.

Return type:: bool

property has_data_errors¶

True if at least one uncertainty source is defined for the data.

Return type:: bool

property has_errors¶

True if at least one uncertainty source is defined for either the data or the model.

Return type:: bool

property model_count¶

The number of model functions contained in the fit, 1 by default.

Return type:: int

property did_fit¶

Whether a fit was performed for the given data and model.

Return type:: bool

property ndf¶

The degrees of freedom of this fit.

Return type:: int

property goodness_of_fit¶

property dynamic_error_algorithm¶: The algorithm to use for handling errors that depend on the model parameters. :rtype: str

property chi2_probability¶: The chi2 probability for the current model values.

property errors_valid¶

set_parameter_values(**param_name_value_dict)¶

Set the fit parameters to new values. Valid keyword arguments are the names of the declared fit parameters.

Parameters:: param_name_value_dict – new parameter values

set_all_parameter_values(param_value_list)¶

Set all the fit parameters at the same time.

Parameters:: param_value_list (Iterable[float]) – List of parameter values (mind the order).

fix_parameter(name, value=None)¶

Fix a parameter so that its value doesn’t change when calling do_fit.

Parameters:

name (str) – The name of the parameter to be fixed
value (float or None) – The value to be given to the fixed parameter. If None the current value from parameter_values will be used.

release_parameter(name)¶

Release a fixed parameter so that its value once again changes when calling do_fit.

Parameters:: name (str) – The name of the fixed parameter to be released

limit_parameter(name, lower=None, upper=None)¶

Limit a parameter to a given range.

Parameters:

name (str) – The name of the parameter to limit.
lower (float) – The minimum parameter value.
upper (float) – The maximum parameter value.

unlimit_parameter(name)¶

Unlimit a parameter.

Parameters:: name (str) – The name of the parameter to unlimit.

add_matrix_parameter_constraint(names, values, matrix, matrix_type='cov', uncertainties=None, relative=False)¶

Advanced class for applying correlated constraints to several parameters of a fit. The order of names, values, matrix, and uncertainties must be aligned. In other words the first index must belong to the first value, the first row/column in the matrix, etc.

Let N be the number of parameters to be constrained.

Parameters:

names (Collection[str]) – The names of the parameters to be constrained. Must be of shape (N,).
values (Sized[float]) – The values to which the parameters should be constrained. Must be of shape shape (N,).
matrix (Iterable[float]) – The matrix that defines the correlation between the parameters. By default interpreted as a covariance matrix. Can also be interpreted as a correlation matrix by setting matrix_type. Must be of shape shape (N, N).
matrix_type (str) – Either 'cov' or 'cor'. Defines whether the matrix should be interpreted as a covariance matrix or as a correlation matrix.
uncertainties (None or Iterable[float]) – The uncertainties to be used in conjunction with a correlation matrix. Must be of shape (N,)
relative (bool) – Whether the covariance matrix/the uncertainties should be interpreted as relative to values.

add_parameter_constraint(name, value, uncertainty, relative=False)¶

Apply a simple gaussian constraint to a single fit parameter.

Parameters:

name (str) – The name of the parameter to be constrained.
value (float) – The value to which the parameter should be constrained.
uncertainty (float) – The uncertainty with which the parameter should be constrained to the given value.
relative (bool) – Whether the given uncertainty is relative to the given value.

get_matching_errors(matching_criteria=None, matching_type='equal')¶

Return a list of uncertainty objects fulfilling the specified matching criteria.

Valid keys for matching_criteria:

name (the unique error name)
type (either 'simple' or 'matrix')
correlated (bool, only matches simple errors!)
reference (either 'model' or 'data')

Note

Parameters:

matching_criteria (dict or None) – Key-value pairs specifying matching criteria. The resulting error array will only contain error objects matching all provided criteria. If None, all error objects are returned.
matching_type (str) – How to perform the matching. If 'equal', the value in matching_criteria is checked for equality against the stored value. If 'regex', the value in matching_criteria is interpreted as a regular expression and is matched against the stored value.

Returns:

Dict mapping error name to GaussianErrorBase-derived error objects.

Return type:

dict[str, kafe2.core.error.GaussianErrorBase]

add_error(err_val, name=None, correlation=0, relative=False, reference='data', **kwargs)¶

Add an uncertainty source to the fit.

Parameters:

err_val (float or Iterable[float]) – Pointwise uncertainty/uncertainties for all data points.
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
correlation (float) – Correlation coefficient between any two distinct data points.
relative (bool) – If True, err_val will be interpreted as a relative uncertainty.
reference (str) – Either 'data' or 'model'. Specifies which reference values to use when calculating absolute errors from relative errors.

Returns:

An error id which uniquely identifies the created error source.

Return type:

str

add_matrix_error(err_matrix, matrix_type, name=None, err_val=None, relative=False, reference='data', **kwargs)¶

Add a matrix uncertainty source for use in the fit.

Parameters:

err_matrix – covariance or correlation matrix
matrix_type (str) – One of 'covariance'/'cov' or 'correlation'/'cor'
name (str or None) – Unique name for this uncertainty source. If None, the name of the error source will be set to a random alphanumeric string.
err_val (Iterable[float]) – The pointwise uncertainties (mandatory if only a correlation matrix is given).
relative (bool) – If True, the covariance matrix and/or err_val will be interpreted as a relative uncertainty.
reference (str) – Either 'data' or 'model'. Specifies which reference values to use when calculating absolute errors from relative errors.

Returns:

An error id which uniquely identifies the created error source.

Return type:

str

disable_error(err_id)¶

Temporarily disable an uncertainty source so that it doesn’t count towards calculating the total uncertainty.

Parameters:: err_id (str) – error id

enable_error(err_id)¶

(Re-)Enable an uncertainty source so that it counts towards calculating the total uncertainty.

Parameters:: err_id (str) – error id

do_fit(asymmetric_parameter_errors=False)¶

Perform the minimization of the cost function.

Parameters:: asymmetric_parameter_errors (bool) – If True, calculate asymmetric parameter errors.
Returns:: A dictionary containing the fit results.
Return type:: dict

assign_model_function_name(name)¶

Assign a string to be the model function name.

Parameters:: name (str) – The new name.

assign_model_function_expression(expression_format_string)¶

Assign a plain-text-formatted expression string to the model function.

Parameters:: expression_format_string (str) – The plain text string.

assign_parameter_names(**par_names_dict)¶

Assign display strings to all model function arguments.

Parameters:: par_names_dict – Dictionary mapping the parameter names to their display names.

assign_model_function_latex_name(latex_name)¶

Assign a LaTeX-formatted string to be the model function name.

Parameters:: latex_name (str) – The LaTeX string.

assign_model_function_latex_expression(latex_expression_format_string)¶

Assign a LaTeX-formatted expression string to the model function.

Parameters:: latex_expression_format_string (str) – The LaTeX string. Elements like '{par_name}' will be replaced automatically with the corresponding LaTeX names for the given parameter. These can be set with assign_parameter_latex_names.

assign_parameter_latex_names(**par_latex_names_dict)¶

Assign LaTeX-formatted strings to all model function arguments.

Parameters:: par_latex_names_dict – Dictionary mapping the parameter names to their latex names.

get_result_dict(asymmetric_parameter_errors=False)¶

Return a dictionary of the fit results.

Parameters:: asymmetric_parameter_errors (bool) – If True, calculate asymmetric parameter errors.
Returns:: A dictionary containing the fit results.
Return type:: dict

report(output_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, show_data=True, show_model=True, show_fit_results=True, asymmetric_parameter_errors=False)¶

Print a summary of the fit state and/or results.

Parameters:

output_stream (io.TextIOBase) – The output stream to which the report should be printed.
show_data (bool) – If True, print out information about the data.
show_model (bool) – If True, print out information about the parametric model.
show_fit_results (bool) – If True, print out information about the fit results.
asymmetric_parameter_errors (bool) – If True, use two different parameter errors for up/down directions.

to_file(filename, file_format=None, calculate_asymmetric_errors=False)¶

Write kafe2 object to file

Parameters:

filename (str) – Filename for the output.
file_format (str or None) – A format for the output file. If None, the extension from the filename is used.
calculate_asymmetric_errors (bool) – If asymmetric errors should be calculated before saving the results.

save_state(filename: str, file_format: str | None = None, calculate_asymmetric_errors: bool = False)¶

Write current state of the fit to file. Unlike to to_file this does not contain information regarding how the fit is constructed - this is because for complex fit objects a reconstruction from e.g. YAML may not work. In such cases the fit object should be contructed via Python and save_state and load_state should be used.

Parameters:

filename (str) – Filename for the output.
file_format (str or None) – A format for the output file. If None, the extension from the filename is used.
calculate_asymmetric_errors (bool) – If asymmetric errors should be calculated before saving the results.

load_state(filename: str, file_format: str | None = None)¶

load current fit state from the specified file that was written with save_state.

Parameters:

filename (str) – Filename for the input.
file_format (str or None) – A format for the output file. If None, the extension from the filename is used.

class kafe2.fit._base.FitEnsembleBase¶

Bases: object

Object for generating ensembles of fits to pseudo-data generated according to the specified uncertainty model.

This is a purely abstract class implementing the minimal interface required by all types of fit ensembles.

FIT_TYPE = None¶

exception kafe2.fit._base.FitEnsembleException¶: Bases: Exception

class kafe2.fit._base.FunctionFormatter(name, latex_name=None, arg_formatters=None, expression_string=None, latex_expression_string=None)¶

Bases: FileIOMixin, object

Base class for function formatter objects. Requires further specialization for each type of model function. Objects derived from this class store information relevant for constructing plain-text and/or LaTeX string representations of functions.

For this, the function name, formatted as a plain-text/LaTeX string, as well as a list of references to ParameterFormatter objects which contain information on how to format the model function arguments is stored.

Optionally, plain-text/LaTeX expression strings can be provided. These are strings representing the model function expression (i.e. mathematical formula).

The formatted string is obtained by calling the get_formatted method.

Construct a formatter for a model function:

Parameters:

name (str) – A plain-text-formatted string indicating the function name.
latex_name (str) – A LaTeX-formatted string indicating the function name.
arg_formatters (list[kafe2.fit._base.ParameterFormatter]) – List of ParameterFormatter-derived objects, formatters for function arguments.
expression_string (str) – A plain-text-formatted string indicating the function expression.
latex_expression_string (str) – A LaTeX-formatted string indicating the function expression.

DEFAULT_EXPRESSION_STRING = None¶

DEFAULT_LATEX_EXPRESSION_STRING = None¶

property expression_format_string¶

A plain-text-formatted expression for the function. This function will replace all function parameters with their corresponding strings. For example the string “{a}*{x}+{b}” will turn into “A*x + B” when the name of the parameter a was set to “A”, and the name of b is set to “B”.

Return type:: str

property latex_expression_format_string¶

A LaTeX-formatted expression for the function. This function will replace all function parameters with their corresponding latex string. For example the string "{a}{x}+{b}" will turn into "A_0 x + B" when the latex name of the parameter a was set to "A_0", and the latex name of b is set to "B".

Return type:: str

property name¶

A plain-text-formatted string indicating the function name.

Return type:: str

property latex_name¶

A LaTeX-formatted string indicating the function name.

Return type:: str

property description¶

A short plain-text description of the function.

Return type:: str

property arg_formatters¶

The list of ParameterFormatter-derived objects used for formatting all model function arguments.

Return type:: list[ParameterFormatter]

property par_formatters¶

List of ParameterFormatter-derived objects used for formatting the fit parameters, excluding the independent parameter(s).

Return type:: list[ParameterFormatter]

get_formatted(with_par_values=False, n_significant_digits=2, format_as_latex=False, with_expression=False)¶

Get a formatted string representing this model function.

Parameters:

with_par_values (bool) – If True, output will include the value of each function parameter (e.g. f(a=1, b=2, ...)).
n_significant_digits (int) – Number of significant digits for rounding.
format_as_latex (bool) – If True, the returned string will be formatted using LaTeX syntax.
with_expression (bool) – If True, the returned string will include the expression assigned to the function.

class kafe2.fit._base.ModelFunctionBase(model_function=<function linear_model>, independent_argcount=1)¶

Bases: FileIOMixin, object

This is a purely abstract class implementing the minimal interface required by all model functions.

In order to be used as a model function, a native Python function must be wrapped by an object whose class derives from this base class. There is a dedicated ModelFunction specialization for each type of data container.

This class provides the basic functionality used by all ModelFunction objects. These use introspection (inspect) for determining the parameter structure of the model function and to ensure the function can be used as a model function (validation).

Construct ModelFunction object (a wrapper for a native Python function):

Parameters:

model_function – function handle
independent_argcount (int) – The amount of independent variables for this model. The first n variables of the model function will be treated as independent variables and will not be fitted.

FORMATTER_TYPE¶: alias of ModelFunctionFormatter

property name¶: The model function name (a valid Python identifier)

property func¶: The underlying model function handle

property signature¶: The model function argument specification, as returned by inspect.signature

property argcount¶: The number of arguments the model function accepts. (including any independent variables which are not parameters)

property parcount¶: The number of fitting parameters in the model function.

property x_name¶: The name of the independent variable. None for 0 independent variables.

property parameter_names¶: The names of the parameters.

property formatter¶: The ModelFunctionFormatter-derived object for this function

property defaults¶: The default values for model function parameters as a list

property defaults_dict¶: The default values for model function parameters as a dict

property source_code¶

class kafe2.fit._base.ModelFunctionFormatter(name, latex_name=None, arg_formatters=None, expression_string=None, latex_expression_string=None)¶

Bases: FunctionFormatter

A formatter class for model functions.

This object stores the function name, formatted as a plain-text/LaTeX string, as well as a list of references to ParameterFormatter objects which contain information on how to format the model function arguments. Additionally formatting information about the independent variable is stored.

Optionally, plain-text/LaTeX expression strings can be provided. These are strings representing the model function expression (i.e. mathematical formula).

The formatted string is obtained by calling the get_formatted method.

Construct a formatter for a model function:

Parameters:

name (str) – A plain-text-formatted string indicating the function name.
latex_name (str) – A LaTeX-formatted string indicating the function name.
arg_formatters (list[kafe2.fit._base.ParameterFormatter]) – List of ParameterFormatter-derived objects, formatters for function arguments.
expression_string (str) – A plain-text-formatted string indicating the function expression.
latex_expression_string (str) – A LaTeX-formatted string indicating the function expression.

property par_formatters¶

List of ParameterFormatter-derived objects used for formatting the fit parameters, excluding the independent parameter(s).

Return type:: list[ParameterFormatter]

get_formatted(with_par_values=False, n_significant_digits=2, format_as_latex=False, with_expression=False)¶

Create a formatted string representing this model function.

Parameters:

with_par_values (bool) – If True, output will include the value of each function parameter (e.g. f(a=1, b=2, ...)).
n_significant_digits (int) – number of significant digits for rounding
format_as_latex (bool) – If True, the returned string will be formatted using LaTeX syntax.
with_expression (bool) – If True, the returned string will include the expression assigned to the function.

Returns:

The formatted string representing this model function.

Return type:

str

class kafe2.fit._base.ParameterFormatter(arg_name, value=None, error=None, asymmetric_error=None, name=None, latex_name=None)¶

Bases: FileIOMixin, object

Formatter class for model parameter objects.

These objects store the relevant information for constructing plain-text and/or LaTeX string representations of model function parameters.

For this, the original argument name, the name for representation, formatted as a plain-text/LaTeX string, its value and its uncertainty is stored.

The formatted string is obtained by calling the get_formatted method.

Construct a Parameter Formatter.

Parameters:

arg_name (str) – A plain string indicating the parameter’s signature inside the function call.
value (float or None) – The parameter value.
error (float or None) – The symmetric parameter error.
asymmetric_error (tuple[float, float] or None) – The asymmetric parameter errors.
name (str or None) – A plain-text-formatted string indicating the parameter name.
latex_name (str or None) – A LaTeX-formatted string indicating the parameter name.

Return type:

ParameterFormatter

property arg_name¶

Name of the function argument this formatter represents.

Return type:: str

property name¶

The plain-text-formatted string indicating the parameter name.

Return type:: str

property latex_name¶

The LaTeX-formatted string indicating the parameter name.

Return type:: str

property value¶

The parameter value.

Return type:: float or None

property error¶

The symmetric parameter error.

Return type:: float or None

property error_rel¶

The relative parameter error.

Return type:: float or None

property asymmetric_error¶

Tuple containing the asymmetric parameter errors.

Return type:: tuple[float, float] or None

property error_up¶

The upper uncertainty (only for asymmetric errors).

Return type:: float or None

property error_down¶

The lower uncertainty (only for asymmetric errors).

Return type:: float or None

property fixed¶

If the parameter has been fixed by the user. True when it’s fixed, False when not.

Return type:: bool

get_formatted(value=None, with_name=False, with_value=True, with_errors=True, n_significant_digits=2, round_value_to_error=True, asymmetric_error=False, format_as_latex=False)¶

Get a formatted string representing this model parameter.

Parameters:

with_name (bool) – If True, the output will include the parameter name.
with_value (bool) – If True, the output will include the parameter value.
with_errors (bool) – If True, the output will include the parameter error(s).
n_significant_digits (int) – Number of significant digits for rounding.
round_value_to_error (bool) – If True, the parameter value will be rounded to the same precision as the uncertainty.
asymmetric_error (bool) – If True, the asymmetric parameter uncertainties are used.
format_as_latex (bool) – If True, the returned string will be formatted using LaTeX syntax.

Returns:

The string representation of the parameter.

Return type:

str

class kafe2.fit._base.ParametricModelBaseMixin(model_func, model_parameters, *args, **kwargs)¶

Bases: object

A “mixin” class for representing a parametric model. Inheriting from this class in addition to a data container class additionally stores a Python function handle referring to the model function. The argument structure of this function must be compatible with the data container type and it must return a numpy array of the same shape as the data property of the data container.

This mixin class introduces an additional parameters property for the object, which can be used to obtain and set the values of the parameter

Derived classes should inherit from ParametricModelBaseMixin and the relevant data container (in that order).

Mixin constructor: sets and initialized the model function.

Parameters:

model_func – handle of Python function (the model function)
model_parameters – iterable of parameter values with which the model function should be initialized

MODEL_FUNCTION_TYPE¶: alias of ModelFunctionBase

property ndf¶

property parameters¶: Model parameter values

class kafe2.fit._base.Plot(fit_objects, separate_figures=False)¶

Bases: object

This is a class implementing the creation of Fits from one of more subclasses of :py:obj`PlotAdapterBase`. Consequently a Plot object manages one or several matplotlib figures. It controls the overall figure layout and is responsible for axes, subplot and legend management.

Parameters:

fit_objects (int or FitBase or Sequence[FitBase]) – which kafe2 fits to use for the plot. A positive integer is interpreted as the fit with the given index that has been performed (with wrappers) since the program started. A negative integer -n is interpreted as the last n fits. kafe2 fit objects are used directly. If a sequence of fit objects is passed they can be displayed as part of the same plot.
separate_figures (bool) – whether the fits should be displayed in separate figures.

FIT_INFO_STRING_FORMAT_CHI2 = '{model_function}\n{parameters}\n $\\hookrightarrow${fit_quality}\n $\\hookrightarrow \\chi^2 \\, \\mathrm{{probability =}}${chi2_probability}\n'¶

FIT_INFO_STRING_FORMAT_SATURATED = '{model_function}\n{parameters}\n $\\hookrightarrow${fit_quality}\n'¶

FIT_INFO_STRING_FORMAT_NOT_SATURATED = '{model_function}\n{parameters}\n $\\hookrightarrow${cost}\n $\\hookrightarrow${fit_quality}\n'¶

property figures¶: The matplotlib figures managed by this object.

property axes¶: A list of dictionaries (one per figure) mapping names to matplotlib Axes objects contained in this figure.

property x_range¶: The plotting x-range for each fit handled by this Plot object. :param: List of tuples containing the x_ranges for each fit. :type: list[tuple[float, float]] or tuple[float, float]

property y_range¶: The plotting y-range for each fit handled by this Plot object. :param: List of tuples containing the y_ranges for each fit. :type: list[tuple[float, float]] or tuple[float, float]

property x_scale¶: The x-scale for each fit used for creating the support values when plotting and axis scaling. :type: list[str] or str

property y_scale¶: The y-scale for each fit used when plotting. :type: list[str] or str

property x_label¶: The x-label(s) of the plot. If multiple fits are handled by this plot this is a list of strings. Multiple labels will be separated by a comma in the final plot while skipping duplicates. If a label is None or '__del__' it will be removed. :type: str or list[str]

property y_label¶: The y-label(s) of the plot. If multiple fits are handled by this plot this is a list of strings. Multiple labels will be separated by a comma in the final plot while skipping duplicates. If a label is None or '__del__' it will be removed. :type: str or list[str]

property x_ticks¶

property y_ticks¶

static show(*args, **kwargs)¶: Convenience wrapper for matplotlib.pyplot.show()

plot(legend=True, fit_info=True, asymmetric_parameter_errors=False, ratio=False, ratio_range=None, ratio_height_share=0.25, residual=False, residual_range=None, residual_height_share=0.25, plot_width_share=0.5, font_scale=1.0, figsize=None)¶

Plot data, model (and other subplots) for all child Fit objects.

Parameters:

legend (bool or Collection[bool]) – if True, a legend is rendered
fit_info – If True, fit results will be shown in the legend. This can also be a list of booleans, corresponding to the fits handled by this Plot-object.
asymmetric_parameter_errors – if True, parameter errors in fit results will be asymmetric
ratio – if True, a secondary plot containing data/model ratios is shown below the main plot
ratio_range (tuple of 2 floats) – the y range to set in the secondary plot
ratio_height_share (float) – share of the total height to be taken up by the secondary plot
plot_width_share (float) – share of the total width to be taken up by the plot(s)
font_scale (float) – multiply font size by this amount.
figsize (tuple of 2 floats) – the (width, height) of the figure (in inches) or None to use default

Returns:

dictionary containing information about the plotted objects

Return type:

dict

get_keywords(plot_type)¶

Retrieve keyword arguments for plots with type plot_type as they would be used when calling plot.

This is an advanced function. An understanding of how plotting with matplotlib and the PlotAdapter classes in kafe2 work is recommended.

The plot_type must be one of the plot types registered in the PlotAdapter (e.g. 'data', 'model_line' etc.).

Parameters:: plot_type (str) – keyword identifying the plot type for which to set a custom keyword argument
Returns:: list of dictionaries (one per fit instance) containing plot keywords and their values
Return type:: list of dict

set_keywords(plot_type, keyword_spec)¶

Set values for keyword arguments used for plots with type plot_type.

This is an advanced function. An understanding of how plotting with matplotlib and the PlotAdapter classes in kafe2 work is recommended.

The plot_type must be one of the plot types registered in the PlotAdapter (e.g. 'data', 'model_line' etc.).

The keyword_spec contains dictionaries whose contents will be passed as keyword arguments to the plot adapter method responsible for plotting the plot_type. If keyword spec contains a key for which a default value is configured, it will be overridden.

Passing the following special values for a keyword will have the following effects:

'__del__': the value will be removed from the keyword arguments. This includes default values, meaning that the plot call will be made without the keyword argument even if a default value for it exists.
'__default__': the customized value will be replaced by the default value.

Note

No keyword/value validation is done: everything is passed to the underlying plot methods as specified. Incorrect or incompatible keywords may be ignored or lead to errors.

As an example, to override the labels shown in the legend entries for the data

p = Plot([fit_1, fit_2])
p.customize('data', [dict(label='My Data Label'), dict(label='Another Data Label')])

To set keywords for a single fit, pass values as (index, value), where index is the index of the fit object:

p = Plot([fit_1, fit_2])
p.customize('data', [(1, dict(label='Another Data Label'))])

Parameters:

plot_type (str) – keyword identifying the plot type for which to set a custom keyword argument
keyword_spec (list of values or list of 2-tuples like (index, value)) – specification of dictionaries containing the keyword arguments to use for fit. Can be either a list of dictionaries with a length corresponding to the number of fit objects managed by this Plot instance, or a list of tuples of the form (index, dict), where index denotes the index of the fit object for which the dictionary dict should be used.

Returns:

this Plot instance

Return type:

Plot

customize(plot_type, keyword, values)¶

Set values for keyword arguments used for plots with type plot_type.

This is a convenience wrapper around set_keywords.

The keyword will be passed to the plot adapter method responsible for plotting the plot_type as a keyword argument with a value taken from values. If a default value for keyword is configured, it is overridden.

The values can be specified in two ways:

as a list with a length corresponding to the number of fit objects managed by this Plot instance. The special value '__skip__' can be used to skip fit objects.
as a list of tuples of the form (index, value), where index denotes the index of the fit object for which the value should be used.

Passing the following special values for a keyword will have the following effects:

'__del__': the value will be removed from the keyword arguments. This includes default values, meaning that the plot call will be made without the keyword argument even if a default value for it exists.
'__default__': the customized value will be replaced by the default value.
'__skip__': the keywords for this fit will not be changed.

Note

No keyword/value validation is done: everything is passed to the underlying plot methods as specified. Incorrect or incompatible keywords may be ignored or lead to errors.

As an example, to override the labels shown in the legend entries for the data

p = Plot([fit_1, fit_2])
p.customize('data', 'label', ['My Data Label', 'Another Data Label'])

To set keywords for a single fit, pass values as (index, value), where index is the index of the fit object:

p = Plot([fit_1, fit_2])
p.customize('data', 'label', [(1, 'Another Data Label')])

Parameters:

plot_type (str) – keyword identifying the plot type for which to set a custom keyword argument
keyword (str) – the keyword argument. The corresponding value in values will be passed to the plot adapter method using this keyword argument
values (list of values or list of 2-tuples like (index, value)) – values that the keyword argument should take for each fit. Can be a list of values with a length corresponding to the number of fit objects managed by this Plot instance, or a list of tuples of the form (index, value)

Returns:

this Plot instance

Return type:

Plot

save(fname=None, figures='all', *args, **kwargs)¶

Saves the plot figures to files. args and kwargs are passed on to matplotlib.Figure.savefig() .

Parameters:

fname (None or str or iterable of str.) – Output file name(s), defaults to fit.png or fit_0.png, fit_1.png, …
figures ('all' or int or iterable of int) – Which figures to save.

class kafe2.fit._base.PlotAdapterBase(fit_object, from_container=False)¶

Bases: object

This is a purely abstract class implementing the minimal interface required by all types of plot adapters.

A PlotAdapter object can be constructed for a Fit object of the corresponding type. Its main purpose is to provide an interface for accessing data stored in the Fit object, for the purposes of plotting. Most importantly, it provides methods to call the relevant matplotlib methods for plotting the data, model (and other information, depending on the fit type), and constructs the arrays required by these routines in a meaningful way.

Classes derived from PlotAdapterBase must at the very least contain properties for constructing the x and y point arrays for both the data and the fitted model, as well as methods calling the matplotlib routines doing the actual plotting.

Construct a PlotAdapter for a Fit object:

Parameters:

fit_object (kafe2.fit._base.FitBase) – An object derived from FitBase
from_container (bool) – Whether fit_object was created ad-hoc from just a data container.

PLOT_STYLE_CONFIG_DATA_TYPE = 'default'¶

PLOT_SUBPLOT_TYPES = {'data': {'container_valid': True, 'plot_adapter_method': 'plot_data', 'target_axes': 'main'}, 'model': {'hide': True, 'plot_adapter_method': 'plot_model', 'target_axes': 'main'}, 'ratio': {'plot_adapter_method': 'plot_ratio', 'plot_style_as': 'data', 'target_axes': 'ratio'}, 'residual': {'plot_adapter_method': 'plot_residual', 'plot_style_as': 'data', 'target_axes': 'residual'}}¶

AVAILABLE_X_SCALES = ('linear',)¶

AVAILABLE_Y_SCALES = ('linear', 'log')¶

call_plot_method(plot_type, target_axes, **kwargs)¶

Call the registered plot method for plot_type.

Parameters:

plot_type (str) – key identifying a registered plot type for this PlotAdapter
target_axes (matplotlib.Axes object) – axes to plot to
kwargs (dict) – keyword arguments to pass to the plot method

Returns:

return value of the plot method

update_plot_kwargs(plot_type, plot_kwargs)¶

Update the value of keyword arguments plot_kwargs to be passed to the plot method for for plot_type.

Parameters:

plot_type (str) – key identifying a registered plot type for this PlotAdapter
plot_kwargs (dict) – dictionary containing keywords arguments to override

abstract property data_x¶

The x coordinates of the data (used by plot_data).

Return type:: numpy.ndarray

abstract property data_y¶

The y coordinates of the data (used by plot_data).

Return type:: numpy.ndarray

abstract property data_xerr¶

The magnitude of the data x error bars (used by plot_data).

Return type:: numpy.ndarray

abstract property data_yerr¶

The magnitude of the data y error bars (used by plot_data).

Return type:: numpy.ndarray

abstract property model_x¶

The x coordinates of the model (used by plot_model).

Return type:: numpy.ndarray

abstract property model_y¶

The y coordinates of the model (used by plot_model).

Return type:: numpy.ndarray

abstract property model_xerr¶

The magnitude of the model x error bars (used by plot_model).

Return type:: numpy.ndarray

abstract property model_yerr¶

The magnitude of the model y error bars (used by plot_model).

Return type:: numpy.ndarray

property x_range¶

The x axis plot range.

Return type:: tuple[float, float]

property y_range¶

The y axis plot range.

Return type:: tuple[float, float]

property x_scale¶

The x axis scale. Available scales are given in AVAILABLE_X_SCALES

Return type:: str

property y_scale¶

The y axis scale. Available scales are given in AVAILABLE_Y_SCALES

Return type:: str

property x_label¶

The x axis label of the fit handled by this plot adapter. If '__del__' is used, the label will be set to None.

Return type:: str

property y_label¶

The x axis label of the fit handled by this plot adapter. If '__del__' is used, the label will be set to None.

Return type:: str

property x_ticks¶

property y_ticks¶

property from_container¶: Whether the contained fit object was created ad-hoc from just a data container.

abstract plot_data(target_axes, **kwargs)¶

Method called by the main plot routine to plot the data points to a specified matplotlib.axes.Axes object.

Parameters:: target_axes (matplotlib.axes.Axes) – The matplotlib target axes.
Returns:: plot handle(s)

abstract plot_model(target_axes, **kwargs)¶

Method called by the main plot routine to plot the model to a specified matplotlib.axes.Axes object.

Parameters:: target_axes (matplotlib.axes.Axes) – The matplotlib target axes.
Returns:: plot handle(s)

plot_ratio(target_axes, error_contributions=('data',), **kwargs)¶

Plot the data/model ratio to a specified matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
error_contributions (str or Tuple[str]) – Which error contributions to include when plotting the data. Can either be data, 'model' or both.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.errorbar.

Returns:

plot handle(s)

plot_residual(target_axes, error_contributions=('data',), **kwargs)¶

Plot the residuals to a matplotlib.axes.Axes object.

Parameters:

target_axes (matplotlib.axes.Axes) – The matplotlib axes used for plotting.
error_contributions (str or Tuple[str]) – Which error contributions to include when plotting the data. Can either be data, 'model' or both.
kwargs (dict) – Keyword arguments accepted by matplotlib.pyplot.errorbar.

Returns:

plot handle(s)

get_formatted_model_function(**kwargs)¶: return model function string

property model_function_parameter_formatters¶: The model function parameter formatters, excluding the independent variable.

class kafe2.fit._base.ScalarFormatter(sigma, n_significant_digits=2)¶

Bases: object

Format a scalar to a specified precision, according to the uncertainty.

Parameters:

sigma (float) – The uncertainty of the parameter.
n_significant_digits (int) – Number of significant digits.

kafe2.fit._base.kc_plot_style(data_type, subplot_key, property_key)¶

kafe2.fit._base.latexify_ascii(ascii_string)¶

Create a true type latex string of an standard ascii string.

Parameters:: ascii_string (str) – The string to be converted
Return type:: str

API Documentation¶

kafe2 Wrappers¶

kafe2 Object-Oriented Programming¶

Parameter Estimation Tools: fit¶

XY Data¶

Indexed data¶

Histograms¶

Unbinned¶

Custom¶

Plots¶

Tools for Fitting xy Data: xy¶

Tools for Fitting Series of Indexed Measurements: indexed¶

Tools for Fitting Histograms: histogram¶

Abstract Base Classes: _base¶

Parameter Estimation Tools: `fit`¶

Tools for Fitting xy Data: `xy`¶

Tools for Fitting Series of Indexed Measurements: `indexed`¶

Tools for Fitting Histograms: `histogram`¶

Abstract Base Classes: `_base`¶