petab.v1.distributions

Probability distributions used by PEtab.

This module provides a set of univariate probability distributions that can be used for sampling and evaluating the probability density function (PDF) and cumulative distribution function (CDF). Most of these distributions also support log transformations and truncation.

Not all distributions that can be represented by these classes are valid as PEtab parameter prior or noise distributions.

Classes

Cauchy(loc, scale[, trunc, log])

Cauchy distribution.

ChiSquare(dof[, trunc, log])

Chi-squared distribution.

Distribution(*[, log, trunc])

A univariate probability distribution.

Exponential(scale[, trunc])

Exponential distribution.

Gamma(shape, scale[, trunc, log])

Gamma distribution.

Laplace(loc, scale[, trunc, log])

A (log-)Laplace distribution.

LogUniform(low, high[, trunc])

A log-uniform or reciprocal distribution.

Normal(loc, scale[, trunc, log])

A (log-)normal distribution.

Rayleigh(scale[, trunc, log])

Rayleigh distribution.

Uniform(low, high, *[, log])

A (log-)uniform distribution.
class petab.v1.distributions.Cauchy(loc: float, scale: float, trunc: tuple[float, float] | None = None, log: bool | float = False)[source]

Bases: Distribution

Cauchy distribution.

A (possibly truncated) Cauchy distribution.

Parameters:

  • loc – The location parameter of the distribution.

  • scale – The scale parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated. If the distribution is log-scaled, the truncation limits are expected to be on the same log scale.

  • log – If True, the distribution is transformed to a log-Cauchy distribution. If a float, the distribution is transformed to a log-Cauchy distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the location and scale parameters are the location and scale of the underlying Cauchy distribution.

property loc: float

The location parameter of the underlying distribution.

property scale: float

The scale parameter of the underlying distribution.

class petab.v1.distributions.ChiSquare(dof: int | float, trunc: tuple[float, float] | None = None, log: bool | float = False)[source]

Bases: Distribution

Chi-squared distribution.

A (possibly truncated) Chi-squared distribution.

Parameters:

  • dof – The degrees of freedom parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated. If the distribution is log-scaled, the truncation limits are expected to be on the same log scale.

  • log – If True, the distribution is transformed to a log-Chi-squared distribution. If a float, the distribution is transformed to a log-Chi-squared distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the degrees of freedom parameter is the degrees of freedom of the underlying Chi-squared distribution.

property dof: int

The degrees of freedom parameter.

class petab.v1.distributions.Distribution(*, log: bool | float = False, trunc: tuple[float, float] = None)[source]

Bases: ABC

A univariate probability distribution.

This class provides a common interface for sampling from and evaluating the probability density function of a univariate probability distribution.

The distribution can be transformed by applying a logarithm to the samples and the PDF. This is useful, e.g., for log-normal distributions.

Parameters:

  • log – If True, the distribution is transformed to its corresponding log distribution (e.g., Normal -> LogNormal). If a float, the distribution is transformed to its corresponding log distribution with the given log-base (e.g., Normal -> Log10Normal). If False, no transformation is applied.

  • trunc – The truncation points (lower, upper) of the distribution or None if the distribution is not truncated. If the distribution is log-scaled, the truncation limits are expected to be on the same log scale.

cdf(x) → ndarray | float[source]

Cumulative distribution function at x.

Parameters:

x – The value at which to evaluate the CDF.

Returns:

The value of the CDF at x.

property logbase: bool | float

The base of the log transformation.

If False, no transformation is applied.

pdf(x) → ndarray | float[source]

Probability density function at x.

Parameters:

x – The value at which to evaluate the PDF.

Returns:

The value of the PDF at x. NaN, if x is outside the domain of the PDF.

ppf(q) → ndarray | float[source]

Percent point function at q.

Parameters:

q – The quantile at which to evaluate the PPF.

Returns:

The value of the PPF at q.

sample(shape=None) → ndarray | float[source]

Sample from the distribution.

Parameters:

shape – The shape of the sample.

Returns:

A sample from the distribution.

property trunc_high: float

The upper truncation limit of the transformed distribution.

property trunc_low: float

The lower truncation limit of the transformed distribution.

class petab.v1.distributions.Exponential(scale: float, trunc: tuple[float, float] | None = None)[source]

Bases: Distribution

Exponential distribution.

A (possibly truncated) Exponential distribution.

Parameters:

  • scale – The scale parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated.

property scale: float

The scale parameter of the underlying distribution.

class petab.v1.distributions.Gamma(shape: float, scale: float, trunc: tuple[float, float] | None = None, log: bool | float = False)[source]

Bases: Distribution

Gamma distribution.

A (possibly truncated) Gamma distribution.

Parameters:

  • shape – The shape parameter of the distribution.

  • scale – The scale parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated.

  • log – If True, the distribution is transformed to a log-Gamma distribution. If a float, the distribution is transformed to a log-Gamma distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the shape and scale parameters are the shape and scale of the underlying Gamma distribution.

property scale: float

The scale parameter of the underlying distribution.

property shape: float

The shape parameter of the underlying distribution.

class petab.v1.distributions.Laplace(loc: float, scale: float, trunc: tuple[float, float] | None = None, log: bool | float = False)[source]

Bases: Distribution

A (log-)Laplace distribution.

Parameters:

  • loc – The location parameter of the distribution.

  • scale – The scale parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated. If the distribution is log-scaled, the truncation limits are expected to be on the same log scale.

  • log – If True, the distribution is transformed to a log-Laplace distribution. If a float, the distribution is transformed to a log-Laplace distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the location and scale parameters are the location and scale of the underlying Laplace distribution.

property loc: float

The location parameter of the underlying distribution.

property scale: float

The scale parameter of the underlying distribution.

class petab.v1.distributions.LogUniform(low: float, high: float, trunc: tuple[float, float] | None = None)[source]

Bases: Distribution

A log-uniform or reciprocal distribution.

A random variable is log-uniformly distributed between low and high if its logarithm is uniformly distributed between log(low) and log(high).

Parameters:

  • low – The lower bound of the distribution.

  • high – The upper bound of the distribution.

  • trunc – The truncation limits of the distribution.

class petab.v1.distributions.Normal(loc: float, scale: float, trunc: tuple[float, float] | None = None, log: bool | float = False)[source]

Bases: Distribution

A (log-)normal distribution.

Parameters:

  • loc – The location parameter of the distribution.

  • scale – The scale parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated. If the distribution is log-scaled, the truncation limits are expected to be on the same log scale.

  • log – If True, the distribution is transformed to a log-normal distribution. If a float, the distribution is transformed to a log-normal distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the location and scale parameters are the location and scale of the underlying normal distribution.

property loc: float

The location parameter of the underlying distribution.

property scale: float

The scale parameter of the underlying distribution.

class petab.v1.distributions.Rayleigh(scale: float, trunc: tuple[float, float] | None = None, log: bool | float = False)[source]

Bases: Distribution

Rayleigh distribution.

A (possibly truncated) Rayleigh distribution.

Parameters:

  • scale – The scale parameter of the distribution.

  • trunc – The truncation limits of the distribution. None if the distribution is not truncated.

  • log – If True, the distribution is transformed to a log-Rayleigh distribution. If a float, the distribution is transformed to a log-Rayleigh distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the scale parameter is the scale of the underlying Rayleigh distribution.

property scale: float

The scale parameter of the underlying distribution.

class petab.v1.distributions.Uniform(low: float, high: float, *, log: bool | float = False)[source]

Bases: Distribution

A (log-)uniform distribution.

Parameters:

  • low – The lower bound of the distribution.

  • high – The upper bound of the distribution.

  • log – If True, the distribution is transformed to a log-uniform distribution. If a float, the distribution is transformed to a log-uniform distribution with the given log-base. If False, no transformation is applied. If a transformation is applied, the lower and upper bounds are the lower and upper bounds of the underlying uniform distribution. Note that this differs from the usual definition of a log-uniform distribution, where the logarithm of the variable is uniformly distributed between the logarithms of the bounds (see also LogUniform).