calibr8.core

This module contains type definitions that generalize across all applications.

Also, it implements a variety of modeling functions such as polynomials, or (asymmetric) logistic functions and their corresponding inverse functions.

class calibr8.core.CalibrationModel(independent_key: str, dependent_key: str, *, theta_names: Sequence[str], ndim: int)

Bases: DistributionMixin

A parent class providing the general structure of a calibration model.

Attributes:

pymc_dist
scipy_dist
theta_fitted: The parameter vector that describes the fitted model.
theta_guess: Initial guess that was used to fit the model.
theta_names: Names of model parameters in a fixed order.
theta_timestamp: The timestamp when theta_fitted was set.

Methods

`infer_independent`(y, *, lower, upper)	Infer the posterior distribution of the independent variable given the observations of the dependent variable.
`likelihood`(*, y, x[, theta, scan_x])	Likelihood of observation (dependent variable) given the independent variable.
`load`(filepath)	Instantiates a model from a JSON file of key properties.
`loglikelihood`(*, y, x[, name, replicate_id, ...])	Loglikelihood of observation (dependent variable) given the independent variable.
`objective`(independent, dependent[, minimize])	Creates an objective function for fitting to data.
`predict_dependent`(x, *[, theta])	Predicts the parameters of a probability distribution which characterises
`predict_independent`(y, *[, theta])	Predict the independent variable using the inverse trend model.
`save`(filepath)	Save key properties of the calibration model to a JSON file.

to_pymc
to_scipy

infer_independent(y: int | float | ndarray, *, lower, upper) → InferenceResult

Infer the posterior distribution of the independent variable given the observations of the dependent variable. A Uniform (lower,upper) prior is applied.

Parameters:

yint, float, array: one or more observations at the same x
lowerfloat: lower limit for uniform distribution of prior
upperfloat: upper limit for uniform distribution of prior

Returns:

posteriorInferenceResult: Result of the independent variable inference.

likelihood(*, y, x, theta=None, scan_x: bool = False)

Likelihood of observation (dependent variable) given the independent variable.

Relies on the loglikelihood method.

Parameters:

yscalar or array-like: observed measurements (dependent variable)
xscalar, array-like or TensorVariable: assumed independent variable
thetaoptional, array-like: model parameters
scan_xbool: When set to True, the method evaluates likelihood(xi, y) for all xi in x

Returns:

Lfloat or TensorVariable: sum of likelihoods

classmethod load(filepath: Path | PathLike)

Instantiates a model from a JSON file of key properties.

Parameters:

filepathpath-like: path to the input file

Returns:

calibrationmodelCalibrationModel: the instantiated calibration model

Raises:

MajorMismatchException: when the major calibr8 version is different
CompatibilityException: when the model type does not match with the savefile

loglikelihood(*, y, x, name: str | None = None, replicate_id: str | None = None, dependent_key: str | None = None, theta=None, **dist_kwargs)

Loglikelihood of observation (dependent variable) given the independent variable.

If both x and y are 1D-vectors, they must have the same length and the likelihood will be evaluated elementwise.

For a 2-dimensional x, the implementation should broadcast and return a result that has the same length as the first dimension of x.

Parameters:

yscalar or array-like: observed measurements (dependent variable)
xscalar, array-like or TensorVariable: assumed independent variable
namestr: Name for the likelihood variable in a PyMC model (tensor mode). Previously this was f’{replicate_id}.{dependent_key}’.
replicate_idoptional, str: Deprecated; pass the name kwarg instead.
dependent_keyoptional, str: Deprecated; pass the name kwarg instead.
thetaoptional, array-like: Parameters for the calibration model to use instead of theta_fitted. The vector must have the correct length, but can have numeric and or symbolic entries. Use this kwarg to run MCMC on calibration model parameters.
**dist_kwargsdict: Additional keyword arguments are forwarded to the PyMC distribution. Most prominent example: dims.

Returns:

Lfloat or TensorVariable: sum of log-likelihoods

objective(independent, dependent, minimize=True) → Callable

Creates an objective function for fitting to data.

Parameters:

independentarray-like: numeric or symbolic values of the independent variable
dependentarray-like: observations of dependent variable
minimizebool: switches between creation of a minimization (True) or maximization (False) objective function

Returns:

objectivecallable: takes a numeric or symbolic parameter vector and returns the (negative) log-likelihood

predict_dependent(x, *, theta=None)

Predicts the parameters of a probability distribution which characterises: the dependent variable given values of the independent variable.

Parameters:

xarray-like: numeric or symbolic independent variable
thetaoptional, array-like: parameters of functions that model the parameters of the dependent variable distribution (defaults to self.theta_fitted)

Returns:

parametersarray-like: parameters characterizing the dependent variable distribution for given [x]

predict_independent(y, *, theta=None)

Predict the independent variable using the inverse trend model.

Parameters:

yarray-like: observations
thetaoptional, array-like: parameters of functions that model the parameters of the dependent variable distribution (defaults to self.theta_fitted)

Returns:

xarray-like: predicted independent values given the observations

save(filepath: Path | PathLike)

Save key properties of the calibration model to a JSON file.

Parameters:

filepathpath-like: path to the output file

property theta_fitted: Tuple[float, ...] | None: The parameter vector that describes the fitted model.

property theta_guess: Tuple[float, ...] | None: Initial guess that was used to fit the model.

property theta_names: Tuple[str, ...]: Names of model parameters in a fixed order.

property theta_timestamp: datetime | None: The timestamp when theta_fitted was set.

class calibr8.core.ContinuousInference(eti_x: ndarray, eti_pdf: ndarray, eti_prob: float, hdi_x: ndarray, hdi_pdf: ndarray, hdi_prob: float)

Bases: InferenceResult

Describes properties common for inference with continuous independent variables.

Attributes:

eti_lower: Lower bound of the ETI.
eti_pdf: Values of the posterior probability density at the positions eti_x.
eti_prob: Probability mass of the given equal tailed interval.
eti_upper: Upper bound of the ETI.
eti_width: Width of the ETI.
eti_x: Values of the independent variable in the interval [eti_lower, eti_upper]
hdi_lower: Lower bound of the HDI.
hdi_pdf: Values of the posterior probability density at the positions hdi_x.
hdi_prob: Probability mass of the given highest density interval.
hdi_upper: Upper bound of the HDI.
hdi_width: Width of the HDI.
hdi_x: Values of the independent variable in the interval [hdi_lower, hdi_upper]

property eti_lower: float | ndarray: Lower bound of the ETI. This is the first value in eti_x.

property eti_pdf: ndarray: Values of the posterior probability density at the positions eti_x.

property eti_prob: float: Probability mass of the given equal tailed interval.

property eti_upper: float | ndarray: Upper bound of the ETI. This is the last value in eti_x.

property eti_width: float | ndarray: Width of the ETI.

property eti_x: ndarray: Values of the independent variable in the interval [eti_lower, eti_upper]

property hdi_lower: float | ndarray: Lower bound of the HDI. This is the first value in hdi_x.

property hdi_pdf: ndarray: Values of the posterior probability density at the positions hdi_x.

property hdi_prob: float: Probability mass of the given highest density interval.

property hdi_upper: float | ndarray: Upper bound of the HDI. This is the last value in hdi_x.

property hdi_width: float | ndarray: Width of the HDI.

property hdi_x: ndarray: Values of the independent variable in the interval [hdi_lower, hdi_upper]

class calibr8.core.ContinuousMultivariateInference(eti_x: ndarray, eti_pdf: ndarray, eti_prob: float, hdi_x: ndarray, hdi_pdf: ndarray, hdi_prob: float)

Bases: ContinuousInference

The result of a multivariate independent variable inference.

Attributes:

eti_lower: Lower bound of the ETI.
eti_pdf: Values of the posterior probability density at the positions eti_x.
eti_prob: Probability mass of the given equal tailed interval.
eti_upper: Upper bound of the ETI.
eti_width: Width of the ETI.
eti_x: Values of the independent variable in the interval [eti_lower, eti_upper]
hdi_lower: Lower bound of the HDI.
hdi_pdf: Values of the posterior probability density at the positions hdi_x.
hdi_prob: Probability mass of the given highest density interval.
hdi_upper: Upper bound of the HDI.
hdi_width: Width of the HDI.
hdi_x: Values of the independent variable in the interval [hdi_lower, hdi_upper]

class calibr8.core.ContinuousMultivariateModel(independent_key: str, dependent_key: str, *, theta_names: Sequence[str], ndim: int)

Bases: CalibrationModel

Attributes:

pymc_dist
scipy_dist
theta_fitted: The parameter vector that describes the fitted model.
theta_guess: Initial guess that was used to fit the model.
theta_names: Names of model parameters in a fixed order.
theta_timestamp: The timestamp when theta_fitted was set.

Methods

`infer_independent`(y, *, lower, upper)	Infer the posterior distribution of the independent variable given the observations of the dependent variable.
`likelihood`(*, y, x[, theta, scan_x])	Likelihood of observation (dependent variable) given the independent variable.
`load`(filepath)	Instantiates a model from a JSON file of key properties.
`loglikelihood`(*, y, x[, name, replicate_id, ...])	Loglikelihood of observation (dependent variable) given the independent variable.
`objective`(independent, dependent[, minimize])	Creates an objective function for fitting to data.
`predict_dependent`(x, *[, theta])	Predicts the parameters of a probability distribution which characterises
`predict_independent`(y, *[, theta])	Predict the independent variable using the inverse trend model.
`save`(filepath)	Save key properties of the calibration model to a JSON file.

to_pymc
to_scipy

infer_independent(y: int | float | ndarray, *, lower, upper) → ContinuousMultivariateInference

Infer the posterior distribution of the independent variable given the observations of the dependent variable. A Uniform (lower,upper) prior is applied.

Parameters:

yint, float, array: one or more observations at the same x
lowerfloat: lower limit for uniform distribution of prior
upperfloat: upper limit for uniform distribution of prior

Returns:

posteriorInferenceResult: Result of the independent variable inference.

class calibr8.core.ContinuousUnivariateInference(median: float, **kwargs)

Bases: ContinuousInference

The result of a numeric infer_independent operation with a univariate model.

Attributes:

eti_lower: Lower bound of the ETI.
eti_pdf: Values of the posterior probability density at the positions eti_x.
eti_prob: Probability mass of the given equal tailed interval.
eti_upper: Upper bound of the ETI.
eti_width: Width of the ETI.
eti_x: Values of the independent variable in the interval [eti_lower, eti_upper]
hdi_lower: Lower bound of the HDI.
hdi_pdf: Values of the posterior probability density at the positions hdi_x.
hdi_prob: Probability mass of the given highest density interval.
hdi_upper: Upper bound of the HDI.
hdi_width: Width of the HDI.
hdi_x: Values of the independent variable in the interval [hdi_lower, hdi_upper]
median: Median of the posterior distribution.

property median: float: Median of the posterior distribution. 50 % of the probability mass on either side.

class calibr8.core.ContinuousUnivariateModel(independent_key: str, dependent_key: str, *, theta_names: Sequence[str])

Bases: CalibrationModel

Attributes:

pymc_dist
scipy_dist
theta_fitted: The parameter vector that describes the fitted model.
theta_guess: Initial guess that was used to fit the model.
theta_names: Names of model parameters in a fixed order.
theta_timestamp: The timestamp when theta_fitted was set.

Methods

`infer_independent`(y, *, lower, upper[, ...])	Infer the posterior distribution of the independent variable given the observations of the dependent variable.
`likelihood`(*, y, x[, theta, scan_x])	Likelihood of observation (dependent variable) given the independent variable.
`load`(filepath)	Instantiates a model from a JSON file of key properties.
`loglikelihood`(*, y, x[, name, replicate_id, ...])	Loglikelihood of observation (dependent variable) given the independent variable.
`objective`(independent, dependent[, minimize])	Creates an objective function for fitting to data.
`predict_dependent`(x, *[, theta])	Predicts the parameters of a probability distribution which characterises
`predict_independent`(y, *[, theta])	Predict the independent variable using the inverse trend model.
`save`(filepath)	Save key properties of the calibration model to a JSON file.

to_pymc
to_scipy

infer_independent(y: int | float | ndarray, *, lower: float, upper: float, steps: int = 300, ci_prob: float = 1) → ContinuousUnivariateInference

Infer the posterior distribution of the independent variable given the observations of the dependent variable. The calculation is done numerically by integrating the likelihood in a certain interval [upper,lower]. This is identical to the posterior with a Uniform (lower,upper) prior.

Parameters:

yint, float, array: One or more observations at the same x.
lowerfloat: Lower limit for uniform distribution of prior.
upperfloat: Upper limit for uniform distribution of prior.
stepsint: Steps between lower and upper or steps between the percentiles (default 300).
ci_probfloat: Probability level for ETI and HDI credible intervals. If 1 (default), the complete interval [upper,lower] will be returned, else the PDFs will be trimmed to the according probability interval; float must be in the interval (0,1]

Returns:

posteriorContinuousUnivariateInference: Result of the numeric posterior calculation.

class calibr8.core.DistributionMixin

Bases: object

Maps the values returned by CalibrationModel.predict_dependent to a SciPy distribution and its parameters, and optionally also to a PyMC distribution and its parameters.

Attributes:

pymc_dist
scipy_dist

Methods

to_pymc
to_scipy

pymc_dist: Literal[None] = None

scipy_dist: rv_continuous | rv_discrete | None = None

to_pymc() → dict

to_scipy() → dict

class calibr8.core.InferenceResult

Bases: object

Generic base type of independent value inference results.

calibr8.core.asymmetric_logistic(x, theta)

5-parameter asymmetric logistic model.

Parameters:

xarray-like

independent variable

thetaarray-like

parameters of the logistic model: L_L: lower asymptote L_U: upper asymptote I_x: x-value at inflection point S: slope at the inflection point c: symmetry parameter (0 is symmetric)

Returns:

yarray-like: dependent variable

calibr8.core.exponential(x, theta)

3-parameter exponential model.

Parameters:

xarray-like: independent variable
thetaarray-like: Parameters of the exponential model: - I: y-axis intercept - L: asymptotic limit - k: kinetic rate

Returns:

yarray-like: dependent variable

calibr8.core.infer_independent(*, likelihood: Callable, y: int | float | ndarray, lower: float, upper: float, steps: int = 300, ci_prob: float = 1) → ContinuousUnivariateInference

Infer the posterior distribution of the independent variable given the observations of the dependent variable. The calculation is done numerically by integrating the likelihood in a certain interval [upper,lower]. This is identical to the posterior with a Uniform (lower,upper) prior.

Parameters:

likelihood: A function that returns a non-logarithmic (!) likelihood that should be integrated. The signature of this function matches the CalibrationModel.likelihood.
yint, float, array: One or more observations at the same x.
lowerfloat: Lower limit for uniform distribution of prior.
upperfloat: Upper limit for uniform distribution of prior.
stepsint: Steps between lower and upper or steps between the percentiles (default 300).
ci_probfloat: Probability level for ETI and HDI credible intervals. If 1 (default), the complete interval [upper,lower] will be returned, else the PDFs will be trimmed to the according probability interval; float must be in the interval (0,1]

Returns:

posteriorContinuousUnivariateInference: Result of the numeric posterior calculation.

calibr8.core.inverse_asymmetric_logistic(y, theta)

Inverse 5-parameter asymmetric logistic model.

Parameters:

yarray-like

dependent variable

thetaarray-like

parameters of the logistic model: L_L: lower asymptote L_U: upper asymptote I_x: x-value at inflection point S: slope at the inflection point c: symmetry parameter (0 is symmetric)

Returns:

xarray-like: independent variable

calibr8.core.inverse_exponential(y, theta)

Inverse of 3-parameter exponential model.

Parameters:

yarray-like: dependent variable
thetaarray-like: Parameters of the exponential model: - I: y-axis intercept - L: asymptotic limit - k: kinetic rate

Returns:

xarray-like: independent variable

calibr8.core.inverse_log_log_logistic(y, theta)

4-parameter log-log logistic model.

Parameters:

yarray-like

dependent variable

thetaarray-like

parameters of the logistic model: I_x: x-value at inflection point (ln(x)) I_y: y-value at inflection point (ln(y)) Lmax: maximum value in log space s: slope at the inflection point

Returns:

xarray-like: independent variable

calibr8.core.inverse_logistic(y, theta)

Inverse 4-parameter logistic model.

Parameters:

yarray-like

dependent variables

thetaarray-like

parameters of the logistic model: I_x: x-value at inflection point I_y: y-value at inflection point Lmax: maximum value s: slope at the inflection point

Returns:

xarray-like: independent variable

calibr8.core.inverse_xlog_asymmetric_logistic(y, theta)

Inverse 5-parameter asymmetric logistic model on log10 independent value.

Parameters:

yarray-like

dependent variable

thetaarray-like

parameters of the logistic model: L_L: lower asymptote L_U: upper asymptote log_I_x: log10(x)-value at x-logarithmic inflection point S: slope at the inflection point (Δy/Δlog10(x)) c: symmetry parameter (0 is symmetric)

Returns:

xarray-like: independent variable

calibr8.core.inverse_xlog_logistic(y, theta)

Inverse 4-parameter x-log logistic model.

Parameters:

yarray-like

dependent variable

thetaarray-like

parameters of the logistic model: I_x: x-value at inflection point (ln(x)) I_y: y-value at inflection point Lmax: maximum value s: slope at the inflection point

Returns:

xarray-like: independent variable

calibr8.core.inverse_ylog_logistic(y, theta)

Inverse 4-parameter y-log logistic model.

Parameters:

yarray-like

dependent variable

thetaarray-like

parameters of the logistic model: I_x: x-value at inflection point I_y: y-value at inflection point (ln(y)) Lmax: maximum value in log space s: slope at the inflection point

Returns:

xarray-like: independent variable

calibr8.core.log_log_logistic(x, theta)

4-parameter log-log logistic model.

Parameters:

xarray-like

independent variable

thetaarray-like

parameters of the log-log logistic model: I_x: inflection point (ln(x)) I_y: inflection point (ln(y)) Lmax: logarithmic maximum value s: slope at the inflection point

Returns:

yarray-like: dependent variable

calibr8.core.logistic(x, theta)

4-parameter logistic model.

Parameters:

xarray-like

independent variable

thetaarray-like

parameters of the logistic model: I_x: x-value at inflection point I_y: y-value at inflection point Lmax: maximum value s: slope at the inflection point

Returns:

yarray-like: dependent variable

calibr8.core.polynomial(x, theta)

Variable-degree polynomical model.

Parameters:

xarray-like: independent variable
thetaarray-like: polynomial coefficients (lowest degree first)

Returns:

yarray-like: dependent variable

calibr8.core.xlog_asymmetric_logistic(x, theta)

5-parameter asymmetric logistic model on log10 independent value.

Parameters:

xarray-like

independent variable

thetaarray-like

parameters of the logistic model: L_L: lower asymptote L_U: upper asymptote log_I_x: log10(x)-value at x-logarithmic inflection point S: slope at the inflection point (Δy/Δlog10(x)) c: symmetry parameter (0 is symmetric)

Returns:

yarray-like: dependent variable

calibr8.core.xlog_logistic(x, theta)

4-parameter x-log logistic model.

Parameters:

xarray-like

independent variable

thetaarray-like

parameters of the log-log logistic model: I_x: inflection point (ln(x)) I_y: inflection point (y) Lmax: maximum value s: slope at the inflection point

Returns:

yarray-like: dependent variable

calibr8.core.ylog_logistic(x, theta)

4-parameter y-log logistic model.

Parameters:

xarray-like

independent variable

thetaarray-like

parameters of the log-log logistic model: I_x: inflection point (x) I_y: inflection point (ln(y)) Lmax: maximum value in log sapce s: slope at the inflection point

Returns:

yarray-like: dependent variables