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:
- 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 akafe2.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:
- 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:
- 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:
- 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, extra=None, 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 ("ratio", "residual", or "pull".) – whether the model error band should be shown.
extra – additional, supplementary plots to show below the main plot.
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:
- 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 cost function value.
- Return type:
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
), anddirect 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 distinct measurements with the (discrete) index ranging from to . The measurements were taken at values . 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 and can also be taken into account by using covariance/correlation matrices.
Additional uncertainites on can also be defined. When fitting an xy model to data they are converted to uncertainties via multiplication with the derivative of the model function by . When plotting the result of xy fits, the model function is displayed as a continuous function of , 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 dataXYParametricModel
: corresponding modelXYFit
: 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 dataIndexedParametricModel
: corresponding modelIndexedFit
: 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 ) is subdivided into a sequence of successive intervals at the “bin edges” . 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 for the first bin and ends at , where is defined as the size of the histogram. The bin numbers and refer to the underflow (below ) and overflow bin (above ), 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 in the bin covering an interval , divided by the total number of entries , will approach the probablity of an event landing in that bin:
In the above formula, is the probability density function, and is an antiderivative of (for example the cumulative distribution function).
Using the above relation, the model prediction for the bin can be defined as:
This means that, for histograms, the model density 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 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 histogramsHistParametricModel
: corresponding modelHistFit
: a fit of a parametric model to histograms
Unbinned
If data is treated as unbinned the model function is interpreted as a model density function. The cost function value is then directly calculated as the negative log-likelihood of the data given said PDF:
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 dataUnbinnedParametricModel
: corresponding modelUnbinnedFit
: 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:
- property data
2D array with shape
(2, size)
containing a copy of the data stored in this container.- Return type:
- property x
1D array of length
[size]
containing the x data.- Return type:
- property x_err
1D array containing the absolute total data x uncertainties.
- Return type:
- property x_cov_mat
2D array of shape
(size, size)
containing the absolute data x covariance matrix.- Return type:
- 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:
- property y
1D array of length
size
containing the y data.- Return type:
- property y_err
1D array of length
size
containing the absolute total data y uncertainties.- Return type:
- property y_cov_mat
2D array of shape
(size, size)
containing the absolute data y covariance matrix.- Return type:
- 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:
- property y_cor_mat
2D array of shape
(size, size)
containing the absolute data y correlation matrix.- Return type:
- add_error(axis, err_val, name=None, correlation=0, relative=False)
Add an uncertainty source for an axis to the data container.
- Parameters:
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:
- 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:
err_matrix (numpy.ndarray) – 2D array of shape
(size, size)
containing the covariance or correlation matrixmatrix_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:
- get_total_error(axis)
Get the error object representing the total uncertainty for a specific axis.
- property has_x_errors
True
if at least one x uncertainty source is defined for the data container.- Return type:
- 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 . This is either ‘covariance’`,
'pointwise'
orNone
.axes_to_use – The errors for the given axes are taken into account when calculating . 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 . This is either ‘covariance’`,
'pointwise'
.axes_to_use – The errors for the given axes are taken into account when calculating . 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.
- 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:
- property has_y_errors
True`
if at least one y uncertainty source has been defined- Return type:
- property x_data
1D array containing the measurement x values.
- Return type:
- property x_model
- .x_data for an
- Return type:
- 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:
- property model
2D array of shape
(2, N)
containing the x and y model values- Return type:
- property x_data_error
1D array containing the pointwise x data uncertainties
- Return type:
- property y_data_error
1D array containing the pointwise y data uncertainties
- Return type:
- property data_error
1D array containing the pointwise xy uncertainties projected onto the y axis.
- Return type:
- property x_data_cov_mat
2D array of shape
(N, N)
containing the data x covariance matrix.- Return type:
- property y_data_cov_mat
2D array of shape
(N, N)
containing the data y covariance matrix.- Return type:
- property data_cov_mat
2D array of shape
(N, N)
containing the data xy covariance matrix (projected onto the y axis).- Return type:
- property x_data_cov_mat_inverse
2D array of shape
(N, N)
containing the inverse of the data x covariance matrix orNone
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 orNone
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:
- property y_data_cor_mat
2D array of shape
(N, N)
containing the data y correlation matrix.- Return type:
- property data_cor_mat
2D array of shape
(N, N)
containing the data xy correlation matrix projected onto the y axis.- Return type:
- property y_model
1D array of y model predictions for the data points.
- Return type:
- property x_model_error
1D array of pointwise model x uncertainties.
- Return type:
- property y_model_error
1D array of pointwise model y uncertainties.
- Return type:
- property model_error
1D array of pointwise model xy uncertainties projected onto the y axis.
- Return type:
- property x_model_cov_mat
2D array of shape
(N, N)
containing the model x covariance matrix.- Return type:
- property y_model_cov_mat
2D array of shape
(N, N)
containing the model y covariance matrix.- Return type:
- property model_cov_mat
2D array of shape
(N, N)
containing the model xy covariance matrix projected onto the y axis.- Return type:
- property x_model_cov_mat_inverse
2D array of shape
(N, N)
containing the inverse of the model x covariance matrix orNone
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 orNone
if singular.- Return type:
- 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:
- property x_model_cor_mat
2D array of shape
(N, N)
containing the model x correlation matrix.- Return type:
- property y_model_cor_mat
2D array of shape
(N, N)
containing the model y correlation matrix.- Return type:
- property model_cor_mat
2D array of shape
(N, N)
containing the model xy correlation matrix projected onto the y axis.- Return type:
- property x_total_error
1D array of total pointwise x uncertainties.
- Return type:
- property y_total_error
1D array of total pointwise y uncertainties
- Return type:
- property total_error
1D array of the total pointwise xy uncertainties projected onto the y axis.
- Return type:
- property x_total_cov_mat
2D array of shape
(N, N)
containing the total x covariance matrix.- Return type:
- property y_total_cov_mat
2D array of shape
(N, N)
containing the total y covariance matrix.- Return type:
- property total_cov_mat
2D array of shape
(N, N)
containing the total xy covariance matrix projected onto the y axis.- Return type:
- 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:
- 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:
- 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:
- property x_total_cor_mat
2D array of shape
(N, N)
containing the total x correlation matrix.- Return type:
- property y_total_cor_mat
2D array of shape
(N, N)
containing the total y correlation matrix.- Return type:
- property x_range
Minimum and maximum values of the x measurement data.
- property y_range
Minimum and maximum values of the y measurement data.
- 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:
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:
- 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:
err_matrix (numpy.ndarray) – 2D array of shape
(size, size)
containing the covariance or correlation matrixmatrix_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:
- 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 valuesx_data
are used.model_parameters (Collection[float]) – The model parameter values. If
None
, the current valuesparameter_values
are used.
- Returns:
Model function values at the given x-values.
- Return type:
- 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 valuesx_data
are used.model_parameters (Collection[float]) – 1D array containing the model parameter values. If
None
, the current valuesparameter_values
are used.par_dx (Collection[float]) – 1D array with length
pars
containing the numeric differentiation step size for each parameter. IfNone
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:
- 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:
- 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 forXYFit
objects by using theadd_error
oradd_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')
.
- 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>}
- 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:
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:
- 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:
err_matrix (numpy.ndarray) – 2D array of shape
(size, size)
containing the covariance or correlation matrixmatrix_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:
- 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.
- 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 variablesstatistics (Iterable[str] or str) – Names of statistics to retrieve for each result variable. If
'all'
, get all statistics for each retrieved variable
- Return type:
- plot_result_distributions(results='all', show_legend=True)
Make plots with histograms of the requested fit variable values across all pseudo-experiments.
- plot_result_scatter(results='all', show_legend=True)
Make scatter plots of the requested fit variable values across all pseudo-experiments.
- 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:
- property x
1D array containing the x support values.
- Return type:
- property y
1D array containing the y values calculated from the x support values and the current parameters.
- Return type:
- 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:
- 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. IfNone
, the model x values are used.model_parameters (Collection[float] or None) – 1D array with length
pars
containing the values of the model parameters. IfNone
, 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:
- 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:
- class kafe2.fit.xy.XYPlotAdapter(xy_fit_object, from_container=False)
Bases:
PlotAdapterBase
Construct an
XYPlotContainer
for aXYFit
object:- Parameters:
- 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'}, 'pull': {'plot_adapter_method': 'plot_pull', 'plot_style_as': 'data', 'target_axes': 'pull'}, '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 model_x
The x coordinates of the model (used by
plot_model
).- Return type:
- property model_y
The y coordinates of the model (used by
plot_model
).- Return type:
- property model_xerr
The magnitude of the model x error bars (used by
plot_model
).- Return type:
- property model_yerr
The magnitude of the model y error bars (used by
plot_model
).- Return type:
- property x_scale
The x axis scale. Available scales are given in
AVAILABLE_X_SCALES
- Return type:
- property model_line_y
y values of the model function at the support points
model_line_x
.- Return type:
- property y_error_band
1D array representing the uncertainty band around the model function at the support points
model_line_x
.- Return type:
- 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.
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
), orNone
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. IfNone
, 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:
- 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. IfNone
, 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:
- 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 . Either
'covariance'
,'pointwise'
orNone
.fallback_on_singular (bool) – If
True
and the covariance matrix is singular (or the errors are zero), calculate as witherrors_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 . 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 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.
- 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 functioncost_function (
CostFunctionBase
-derived or unwrapped native Python function) – the cost functionminimizer (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 argumentsexpression_string – a plain-text-formatted string indicating the function expression
latex_expression_string – a LaTeX-formatted string indicating the function expression
- 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 syntaxwith_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 (ifNone
, the current values are used)- Returns:
value(s) of the model function for the given parameters
- Return type:
- 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 (ifNone
, 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:
- class kafe2.fit.indexed.IndexedPlotAdapter(indexed_fit_object, from_container=False)
Bases:
PlotAdapterBase
Construct an
IndexedPlotContainer
for aIndexedFit
object:- Parameters:
fit_object – an
IndexedFit
objectfrom_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'}, 'pull': {'plot_adapter_method': 'plot_pull', 'plot_style_as': 'data', 'target_axes': 'pull'}, '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
forIndexedPlotContainer
- 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
forIndexedPlotContainer
- 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
objectkwargs – keyword arguments accepted by the
matplotlib
methodserrorbar
orplot
- Returns:
plot handle(s)
- plot_model(target_axes, **kwargs)
Plot the model predictions to a specified matplotlib
Axes
object.- Parameters:
target_axes –
matplotlib
Axes
objectkwargs – 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.
- 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 . Either
'covariance'
,'pointwise'
orNone
.fallback_on_singular (bool) – If
True
and the covariance matrix is singular (or the errors are zero), calculate as witherrors_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 . 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 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.
- 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 functionbin_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:
- Returns:
model function density values
- Return type:
- 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:
- Returns:
value(s) of the model function for the given parameters
- Return type:
- class kafe2.fit.histogram.HistPlotAdapter(hist_fit_object, from_container=False)
Bases:
PlotAdapterBase
Construct an
HistPlotContainer
for aHistFit
object:- Parameters:
- 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'}, 'pull': {'plot_adapter_method': 'plot_pull', 'plot_style_as': 'data', 'target_axes': 'pull'}, '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
forHistPlotContainer
- 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
objectkwargs – keyword arguments accepted by the
matplotlib
methoderrorbar
- Returns:
plot handle(s)
- plot_model(target_axes, **kwargs)
Plot the model predictions to a specified matplotlib
Axes
object.- Parameters:
target_axes –
matplotlib
Axes
objectkwargs – keyword arguments accepted by the
matplotlib
methodbar
- 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
objectkwargs – keyword arguments accepted by the
matplotlib
methodplot
- Returns:
plot handle(s)
Tools for Unbinned Fits: unbinned
This submodule provides the necessary objects for parameter estimation from unbinned datasets. Those fits are used when there are two few data points to fill a histogram. Unbinned fits are essentially the ground truth for histogram fits as there is no modification of the data points through the binning. As each data point is considered, performing an unbinned fit can take much longer than a histogram fit, where each bin is considered.
- synopsis:
This submodule provides the necessary objects for parameter estimation from unbinned datasets.
- class kafe2.fit.unbinned.UnbinnedContainer(data, dtype=<class 'float'>)
Bases:
IndexedContainer
This object is a specialized data container for series of 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
- add_error()
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. IfNone
, 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:
- add_matrix_error()
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. IfNone
, 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:
- class kafe2.fit.unbinned.UnbinnedCostFunction_NegLogLikelihood
Bases:
CostFunction
Built-in negative log-likelihood cost function for Unbinned data.
When using an unbinned dataset, the negative log-likelihood is the best method to fit a probability density funtion pdf to the density of the datapoints
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.
- static nll(model)
- class kafe2.fit.unbinned.UnbinnedFit(data, model_function='normal_distribution', cost_function=<kafe2.fit.unbinned.cost.UnbinnedCostFunction_NegLogLikelihood object>, minimizer=None, minimizer_kwargs=None)
Bases:
FitBase
Construct a fit to a model of unbinned data.
- Parameters:
data – the data points
model_function (
ModelFunctionBase
or unwrapped native Python function) – the model densitycost_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
UnbinnedContainer
- MODEL_TYPE
alias of
UnbinnedParametricModel
- MODEL_FUNCTION_TYPE
alias of
ModelFunctionBase
- PLOT_ADAPTER_TYPE
alias of
UnbinnedPlotAdapter
- RESERVED_NODE_NAMES = {'cost', 'data', 'model', 'parameter_constraints', 'parameter_values'}
- property data_range
The minimum and maximum value of the data
- property model
array of model predictions for the data points
- property goodness_of_fit
- eval_model_function(x=None, model_parameters=None)
Evaluate the model function.
- Parameters:
- Returns:
model function values
- Return type:
- report(output_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, 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.
- class kafe2.fit.unbinned.UnbinnedParametricModel(data, model_density_function=<function normal_distribution>, model_parameters=[1.0, 1.0])
Bases:
ParametricModelBaseMixin
,UnbinnedContainer
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
- property support
- property data
container data (one-dimensional
numpy.ndarray
)
- eval_model_function(support=None, model_parameters=None)
Evaluate the model function.
- Parameters:
support (list or
None
) – x values of the support points (ifNone
, the model support values are used)model_parameters (list or
None
) – values of the model parameters (ifNone
, the current values are used)
- Returns:
value(s) of the model function for the given parameters
- Return type:
- class kafe2.fit.unbinned.UnbinnedPlotAdapter(unbinned_fit_object, from_container=False)
Bases:
PlotAdapterBase
Construct an
UnbinnedPlotAdapter
for aUnbinnedFit
object:- Parameters:
unbinned_fit_object – an
UnbinnedFit
objectfrom_container (bool) – Whether unbinned_fit_object was created ad-hoc from just a data container.
- PLOT_STYLE_CONFIG_DATA_TYPE = 'unbinned'
- 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_line': {'plot_adapter_method': 'plot_model_line', 'target_axes': 'main'}, 'pull': {'plot_adapter_method': 'plot_pull', 'plot_style_as': 'data', 'target_axes': 'pull'}, '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 model_x
x support values for model function
- property model_y
The ‘y’ coordinates of the model (used by
plot_model
).- Returns:
iterable
- property model_line_x
x support values for model function
- property model_line_y
The ‘y’ coordinates of the model (used by
plot_model
).- Returns:
iterable
- property model_xerr
The magnitude of the model ‘x’ error bars (used by
plot_model
).- Returns:
iterable
- property model_yerr
The magnitude of the model ‘y’ error bars (used by
plot_model
).- Returns:
iterable
- property x_scale
The x axis scale. Available scales are given in
AVAILABLE_X_SCALES
- Return type:
- plot_data(target_axes, height=None, **kwargs)
Method called by the main plot routine to plot the data points to a specified matplotlib
Axes
object.- Parameters:
target_axes –
matplotlib
Axes
objectheight (float) – The height of the lines which represent the density
- Returns:
plot handle(s)
- plot_model(target_axes, **kwargs)
Method called by the main plot routine to plot the model to a specified matplotlib
Axes
object.- Parameters:
target_axes –
matplotlib
Axes
objectkwargs – keyword arguments accepted by the
step_fill_between
method
- 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)
- plot_model_line(target_axes, **kwargs)
Method called by the main plot routine to plot the model to a specified matplotlib
Axes
object.- Parameters:
target_axes –
matplotlib
Axes
objectkwargs – keyword arguments accepted by the
step_fill_between
method
- 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.
- 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:
- property latex_name_saturated
A LaTeX-formatted string indicating the saturated function name.
- Return type:
- 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 namesaturated (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 valueformat_as_latex (bool) – If
True
, the returned string will be formatted using LaTeX syntax
- Return type:
- 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 . Either
'covariance'
,'pointwise'
orNone
.fallback_on_singular (bool) – If
True
and the covariance matrix is singular (or the errors are zero), calculate as witherrors_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:
In the above, are the measurements, are the model predictions, and is the additional cost resulting from any constrained parameters.
- Parameters:
data – measurement data
model – model predictions
- 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:
In the above, are the measurements, are the model predictions, is the inverse of the total covariance matrix, is the additional cost resulting from any constrained parameters, and is the additional cost to compensate for a non-constant covariance matrix.
- Parameters:
data – measurement data
model – model predictions
total_cov_mat_cholesky – Cholesky decomposition of the total covariance matrix with
- 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:
In the above, are the measurements, are the model predictions, are the pointwise total uncertainties, is the additional cost resulting from any constrained parameters, and is the additional cost to compensate for non-constant errors.
- Parameters:
data – measurement data
model – model predictions
total_error – total error vector
- 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 . 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:
In the above, are the measurements, are the model predictions, is the inverse of the total covariance matrix, is the additional cost resulting from any constrained parameters, and is the additional cost to compensate for a non-constant covariance matrix.
- Parameters:
data – measurement data
model – model predictions
total_cov_mat – The total covariance matrix
- 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:
In the above, are the measurements, are the model predictions, are the pointwise total uncertainties, is the additional cost resulting from any constrained parameters, and is the additional cost to compensate for non-constant errors.
- Parameters:
data – measurement data
model – model predictions
total_error – total error vector
- 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 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:
- static nll_gaussian(data, model, total_error)
A negative log-likelihood function assuming Gaussian statistics for each measurement.
The cost function is given by:
In the above, are the measurements, are the model predictions, are the pointwise total uncertainties, and is the additional cost resulting from any constrained parameters.
- Parameters:
data – measurement data
model – model predictions
total_error – total error vector
- 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:
In the above, are the measurements, are the model predictions, and is the additional cost resulting from any constrained parameters.
- Parameters:
data – measurement data
model – model predictions
- 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 axis_labels
The axis labels describing the dataset.
- abstract property data
A numpy array containing the data values.
- Return type:
- abstract property err
A numpy array containing the pointwise data uncertainties.
- Return type:
- abstract property cov_mat
A numpy matrix containing the covariance matrix of the data.
- Return type:
- 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:
- 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:
- 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:
- 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
(eithersimple
ormatrix
)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:
- 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:
- 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:
- 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:
- property parameter_values
The current parameter values.
- Return type:
- property parameter_errors
The current parameter uncertainties. Can be set to control initial step size during minimization.
- Return type:
- 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:
- property parameter_name_value_dict
A dictionary mapping each parameter name to its current value.
- property parameter_constraints
The gaussian constraints given for the fit parameters.
- Return type:
list[kafe2.core.constraint.GaussianSimpleParameterConstraint or kafe2.core.constraint.GaussianMatrixParameterConstraint]
- property has_model_errors
True
if at least one uncertainty source is defined for the model.- Return type:
- property has_data_errors
True
if at least one uncertainty source is defined for the data.- Return type:
- property has_errors
True
if at least one uncertainty source is defined for either the data or the model.- Return type:
- property model_count
The number of model functions contained in the fit, 1 by default.
- Return type:
- 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.
- 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 fromparameter_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.
- 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
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 dataset 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:
- 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:
- 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:
- 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.
- 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 withassign_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.
- 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
- 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.
- 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
- 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:
- 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 parametera
was set to"A_0"
, and the latex name ofb
is set to"B"
.- Return type:
- property arg_formatters
The list of
ParameterFormatter
-derived objects used for formatting all model function arguments.- Return type:
- property par_formatters
List of
ParameterFormatter
-derived objects used for formatting the fit parameters, excluding the independent parameter(s).- Return type:
- 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:
- 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:
- 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:
- property asymmetric_error
Tuple containing the asymmetric parameter errors.
- property fixed
If the parameter has been fixed by the user.
True
when it’s fixed,False
when not.- Return type:
- 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:
- 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 parameterDerived 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 severalmatplotlib
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, pull=False, pull_range=None, pull_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 renderedfit_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 thisPlot
-object.asymmetric_parameter_errors – if
True
, parameter errors in fit results will be asymmetricratio – if
True
, a secondary plot containing data/model ratios is shown below the main plotratio_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:
- 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.).
- 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)
, whereindex
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() .
- 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 aFit
object of the corresponding type. Its main purpose is to provide an interface for accessing data stored in theFit
object, for the purposes of plotting. Most importantly, it provides methods to call the relevantmatplotlib
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 thematplotlib
routines doing the actual plotting.Construct a
PlotAdapter
for aFit
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'}, 'pull': {'plot_adapter_method': 'plot_pull', 'plot_style_as': 'data', 'target_axes': 'pull'}, '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.
- 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.
- abstract property data_xerr
The magnitude of the data x error bars (used by
plot_data
).- Return type:
- abstract property data_yerr
The magnitude of the data y error bars (used by
plot_data
).- Return type:
- abstract property model_x
The x coordinates of the model (used by
plot_model
).- Return type:
- abstract property model_y
The y coordinates of the model (used by
plot_model
).- Return type:
- abstract property model_xerr
The magnitude of the model x error bars (used by
plot_model
).- Return type:
- abstract property model_yerr
The magnitude of the model y error bars (used by
plot_model
).- Return type:
- property x_scale
The x axis scale. Available scales are given in
AVAILABLE_X_SCALES
- Return type:
- property y_scale
The y axis scale. Available scales are given in
AVAILABLE_Y_SCALES
- Return type:
- property x_label
The x axis label of the fit handled by this plot adapter. If
'__del__'
is used, the label will be set toNone
.- Return type:
- property y_label
The x axis label of the fit handled by this plot adapter. If
'__del__'
is used, the label will be set toNone
.- Return type:
- 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)
- plot_pull(target_axes, error_contributions=('data',), **kwargs)
Plot the pull of the data values on the model 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)
- 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.
- kafe2.fit._base.kc_plot_style(data_type, subplot_key, property_key)