Distribution functions¶

The escape.core.distribution module provides functors for several commonly used distribution functions:

Gamma distribution: \(1/ heta\exp((k-1)\log(t)-x/ heta-\log(\Gamma(k)))\)
Schulz-Zimm distribution: \(t/x\exp((k-1)\log(t)-t-\log(\Gamma(k)))\)
Lognormal distribution: \(\exp(\log^2(x/x_0)/(2\sigma^2))/(\sqrt(2\pi)\sigma x)\)
Normal (Gaussian) distribution: \(1/(\sqrt(2\pi)\sigma)\exp(-(x-x_0)^2/(2\sigma^2))\)
Uniform distribution: \(1/w\) for \(x_0-w/2<=x<=x_0+w/2\)
Triangular distribution: \(2(x-a)/(b-a)/(x_0-a)\) for \(a<=x<=x_0\), \(2(b-x)/(b-a)/(b-x_0)\) for \(x_0<=x<=b\)

Usage notes¶

The distribution functions normal, uniform and triangular use the full width at half maximum (FWHM) as the width parameter instead of \(\sigma\). For the normal distribution, \(\sigma = FWHM/2.355\).

All distribution functions take three arguments:

x: The coordinate variable/functor/parameter
mean: The mean/center value variable/functor/parameter
width: The width parameter variable/functor/parameter (either sigma or fwhm)

The input arguments x and mean must be of the same type - either both functors or both parameters. The width parameter can be either a functor or parameter, independent of the type of x and mean.

Variables and numeric constants are automatically converted: - Variables are converted to identity functions - Numeric constants are converted to parameters with constant values

Examples¶

Create a gamma distribution with all variable inputs:

>>> x = esc.var("x")
>>> x0 = esc.var("x0") 
>>> s = esc.var("s")
>>> d = esc.gamma("Gamma", x, x0, s)
>>> type(d)
  <class 'escape.core.objects.functor_obj'>
>>> d.variables()
  [variable(name='x'), variable(name='x0'), variable(name='s')]
>>> d(1, 1, 2)
  0.15189039329751247

Create a gamma distribution with parameter inputs and variable width:

>>> x = esc.par("x", 1)
>>> x0 = esc.par("x0", 1)
>>> s = esc.var("s")
>>> d = esc.gamma("Gamma", x, x0, s)
>>> type(d)
  <class 'escape.core.objects.functor_obj'>
>>> d.variables()
  [variable(name='s')]
>>> d(2)
  0.15189039329751247

Create a gamma distribution with all parameter inputs:

>>> x = esc.par("x", 1)
>>> x0 = esc.par("x0", 1)
>>> s = esc.par("s", 2)
>>> d = esc.gamma("Gamma", x, x0, s)
>>> type(d)
  <class 'escape.core.objects.parameter_obj'>
>>> d.value
  0.15189039329751247

Mixing parameter and variable inputs for x and mean raises an error:

>>> d = esc.gamma("Gamma", 1, esc.var("x0"), s = esc.par("s", 2))
  Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "escape\core\distribution.pyx", line 138, in escape.core.distribution.gamma
  TypeError:  Wrong type of `x` and `mean` argument, expected for both `parameter_obj`, `variable_obj` or `functor_obj` got <class 'int'>, <class 'escape.core.objects.variable_obj'>

escape.core.distribution.gamma(name: str, x: InputType, mean: InputType, sigma: Union[FunctorType, ParamType]) → Union[functor_obj, parameter_obj]¶

Gamma distribution functor.

Implements the gamma distribution: \(1/\theta\exp((k-1)\log(t)-x/\theta-\log(\Gamma(k)))\), where \(\theta=\sigma^2x_0\), \(k=x_0/\theta\), \(t=x/\theta\).

Args:: name: Name of the functor. Ignored if returned object is a parameter x: Coordinate variable/functor/parameter mean: Mean value variable/functor/parameter sigma: Width parameter variable/functor/parameter
Returns:: A functor_obj or parameter_obj depending on input types
Raises:: TypeError: If input argument types are incompatible

escape.core.distribution.schulz(name: str, x: InputType, mean: InputType, sigma: Union[FunctorType, ParamType]) → Union[functor_obj, parameter_obj]¶

Schulz-Zimm distribution functor.

Implements the Schulz-Zimm distribution: \(t/x\exp((k-1)\log(t)-t-\log(\Gamma(k)))\), where \(k=1/\sigma^2\), \(t=kx/x_0\).

Args:: name: Name of the functor. Ignored if returned object is a parameter x: Coordinate variable/functor/parameter mean: Mean value variable/functor/parameter sigma: Width parameter variable/functor/parameter
Returns:: A functor_obj or parameter_obj depending on input types
Raises:: TypeError: If input argument types are incompatible

escape.core.distribution.lognorm(name: str, x: InputType, mean: InputType, sigma: Union[FunctorType, ParamType]) → Union[functor_obj, parameter_obj]¶

Lognormal distribution functor.

Implements the lognormal distribution: \(\exp(\log^2(x/x_0)/(2\sigma^2))/(\sqrt(2\pi)\sigma x)\)

Args:: name: Name of the functor. Ignored if returned object is a parameter x: Coordinate variable/functor/parameter mean: Mean value variable/functor/parameter sigma: Width parameter variable/functor/parameter
Returns:: A functor_obj or parameter_obj depending on input types
Raises:: TypeError: If input argument types are incompatible

escape.core.distribution.normal(name: str, x: InputType, mean: InputType, fwhm: Union[FunctorType, ParamType]) → Union[functor_obj, parameter_obj]¶

Normal (Gaussian) distribution functor.

Implements the normal distribution: \(1/(\sqrt(2\pi)\sigma)\exp(-(x-x_0)^2/(2\sigma^2))\), where \(\sigma = FWHM/2.355\)

Args:: name: Name of the functor. Ignored if returned object is a parameter x: Coordinate variable/functor/parameter mean: Mean value variable/functor/parameter fwhm: Full width at half maximum variable/functor/parameter
Returns:: A functor_obj or parameter_obj depending on input types
Raises:: TypeError: If input argument types are incompatible

escape.core.distribution.uniform(name: str, x: InputType, mean: InputType, fwhm: Union[FunctorType, ParamType]) → Union[functor_obj, parameter_obj]¶

Uniform distribution functor.

Implements the uniform distribution: \(G(x; x_0, FWHM) = 1.0 / w\), for \(x_0-w/2<=x<=x_0+w/2\) and \(w==FWHM\)

Args:: name: Name of the functor. Ignored if returned object is a parameter x: Coordinate variable/functor/parameter mean: Mean value variable/functor/parameter fwhm: Full width at half maximum variable/functor/parameter
Returns:: A functor_obj or parameter_obj depending on input types
Raises:: TypeError: If input argument types are incompatible

escape.core.distribution.triangular(name: str, x: InputType, mean: InputType, fwhm: Union[FunctorType, ParamType]) → Union[functor_obj, parameter_obj]¶

Triangular distribution functor.

Implements the triangular distribution: \(G(x; x_0, w) = 2 (x - a) / (b - a) / (x_0 - a)\), for \(a<=x<=x_0\) \(G(x; x_0, w) = 2 (b - x) / (b - a) / (b - x_0)\), for \(x_0<=x<=b\), where \(a=x_0-w\) and \(b=x_0+w\) and \(w==FWHM\)

Args:: name: Name of the functor. Ignored if returned object is a parameter x: Coordinate variable/functor/parameter mean: Mean value variable/functor/parameter fwhm: Full width at half maximum variable/functor/parameter
Returns:: A functor_obj or parameter_obj depending on input types
Raises:: TypeError: If input argument types are incompatible