leaspy.variables.distributions

This module defines the distributions used for sampling variables.

Attributes

`Normal`
`Bernoulli`
`WeibullRightCensored`
`WeibullRightCensoredWithSources`

Classes

`StatelessDistributionFamily`	Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).
`StatelessDistributionFamilyFromTorchDistribution`	Wrapper to build a StatelessDistributionFamily class from an existing torch distribution class.
`BernoulliFamily`	Bernoulli family (stateless).
`NormalFamily`	Normal / Gaussian family (stateless).
`AbstractWeibullRightCensoredFamily`	Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).
`WeibullRightCensoredFamily`	Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).
`WeibullRightCensoredWithSourcesFamily`	Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).
`SymbolicDistribution`	Class providing symbolic methods for distribution families.

Module Contents

class StatelessDistributionFamily

Bases: abc.ABC

Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).

TODO / WIP? allow WeightedTensor for parameters as well? (e.g. batched_deltas = Normal(batched_deltas_mean, …) which should be masked at some indices) –> mask at latent pop. variable level (batched_deltas) or

directly at model parameter level batched_deltas_mean?

parameters: ClassVar[tuple[str, Ellipsis]]

classmethod validate_parameters(*params)

Abstractmethod:
Parameters:: params (Any)
Return type:: tuple[Tensor, Ellipsis]

Validate consistency of distribution parameters, returning them with out-of-place modifications if needed.

classmethod shape(*params_shapes)

Shape of distribution samples (without any additional expansion), given shapes of distribution parameters.

Parameters:: params_shapes (tuple[int, Ellipsis])
Return type:: tuple[int, Ellipsis]

classmethod sample(*params, sample_shape=())

Abstractmethod:

Parameters:

params (Tensor)
sample_shape (tuple[int, Ellipsis])

Return type:

Tensor

Sample values, given distribution parameters (sample_shape is prepended to shape of distribution parameters).

classmethod mode(*params)

Abstractmethod:
Parameters:: params (Tensor)
Return type:: Tensor

Mode of distribution (returning first value if discrete ties), given distribution parameters.

classmethod mean(*params)

Abstractmethod:
Parameters:: params (Tensor)
Return type:: Tensor

Mean of distribution (if defined), given distribution parameters.

classmethod stddev(*params)

Abstractmethod:
Parameters:: params (Tensor)
Return type:: Tensor

Standard-deviation of distribution (if defined), given distribution parameters.

classmethod nll(x, *params)

Negative log-likelihood of value, given distribution parameters.

Parameters:

x (WeightedTensor[float])
params (Tensor)

Return type:

WeightedTensor[float]

classmethod regularization(x, *params)

Negative log-likelihood of value, given distribution parameters.

Parameters:

x (Tensor)
params (Tensor)

Return type:

WeightedTensor[float]

classmethod nll_jacobian(x, *params)

Jacobian w.r.t. value of negative log-likelihood, given distribution parameters.

Parameters:

x (WeightedTensor[float])
params (Tensor)

Return type:

WeightedTensor[float]

classmethod nll_and_jacobian(x, *params)

Negative log-likelihood of value and its jacobian w.r.t. value, given distribution parameters.

Parameters:

x (WeightedTensor[float])
params (Tensor)

Return type:

tuple[WeightedTensor[float], WeightedTensor[float]]

class StatelessDistributionFamilyFromTorchDistribution

Bases: StatelessDistributionFamily

Wrapper to build a StatelessDistributionFamily class from an existing torch distribution class.

dist_factory: ClassVar[Callable[Ellipsis, torch.distributions.Distribution]]

classmethod validate_parameters(*params)

Validate consistency of distribution parameters, returning them with out-of-place modifications if needed.

Parameters:

paramsAny: The parameters to pass to the distribution factory.

Returns:

tuple [ torch.Tensor, …]: The validated parameters.

Parameters:

params (Any)

Return type:

tuple[Tensor, Ellipsis]

classmethod sample(*params, sample_shape=())

Sample values, given distribution parameters (sample_shape is prepended to shape of distribution parameters).

Parameters:

params (Tensor)
sample_shape (tuple[int, Ellipsis])

Return type:

Tensor

classmethod mode(*params)

Abstractmethod:
Parameters:: params (Tensor)
Return type:: Tensor

Mode of distribution (returning first value if discrete ties), given distribution parameters.

Parameters:

paramstorch.Tensor: The distribution parameters.

Returns:

torch.Tensor: The value of the distribution’s mode.

Parameters:

params (Tensor)

Return type:

Tensor

classmethod mean(*params)

Return the mean of the distribution, if defined.

Parameters:

paramstorch.Tensor: The distribution parameters.

Returns:

torch.Tensor: The value of the distribution’s mean.

Parameters:

params (Tensor)

Return type:

Tensor

classmethod stddev(*params)

Return the standard-deviation of the distribution.

Parameters:

paramstorch.Tensor: The distribution parameters.

Returns:

torch.Tensor: The value of the distribution’s standard deviation.

Parameters:

params (Tensor)

Return type:

Tensor

class BernoulliFamily

Bases: StatelessDistributionFamilyFromTorchDistribution

Bernoulli family (stateless).

parameters: ClassVar = ('loc',)

dist_factory: ClassVar

class NormalFamily

Bases: StatelessDistributionFamilyFromTorchDistribution

Normal / Gaussian family (stateless).

parameters: ClassVar = ('loc', 'scale')

dist_factory: ClassVar

nll_constant_standard: ClassVar

classmethod mode(loc, scale)

Return the mode of the distribution given the distribution’s loc and scale parameters.

Parameters:

loctorch.Tensor: The distribution loc.
scaletorch.Tensor: The distribution scale.

Returns:

torch.Tensor: The value of the distribution’s mode.

Parameters:

loc (Tensor)
scale (Tensor)

Return type:

Tensor

classmethod mean(loc, scale)

Return the mean of the distribution, given the distribution loc and scale parameters.

Parameters:

loctorch.Tensor: The distribution loc parameters.
scaletorch.Tensor: The distribution scale parameters.

Returns:

torch.Tensor: The value of the distribution’s mean.

Parameters:

loc (Tensor)
scale (Tensor)

Return type:

Tensor

classmethod stddev(loc, scale)

Return the standard-deviation of the distribution, given loc and scale of the distribution.

Parameters:

loctorch.Tensor: The distribution loc parameter.
scaletorch.Tensor: The distribution scale parameter.

Returns:

torch.Tensor: The value of the distribution’s standard deviation.

Parameters:

loc (Tensor)
scale (Tensor)

Return type:

Tensor

class AbstractWeibullRightCensoredFamily

Bases: StatelessDistributionFamily

Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).

TODO / WIP? allow WeightedTensor for parameters as well? (e.g. batched_deltas = Normal(batched_deltas_mean, …) which should be masked at some indices) –> mask at latent pop. variable level (batched_deltas) or

directly at model parameter level batched_deltas_mean?

dist_weibull: ClassVar

precision: float = 0.0001

classmethod validate_parameters(*params)

Abstractmethod:
Parameters:: params (Any)
Return type:: tuple[Tensor, Ellipsis]

Validate consistency of distribution parameters, returning them with out-of-place modifications if needed.

Parameters:

paramsAny: The parameters to pass to the distribution factory.

Returns:

tuple [ torch.Tensor, …]: The validated parameters.

Parameters:

params (Any)

Return type:

tuple[Tensor, Ellipsis]

classmethod sample(nu, rho, xi, tau, sample_shape=())

Sample values, given distribution parameters (sample_shape is prepended to shape of distribution parameters).

Parameters:

nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)
sample_shape (tuple[int, Ellipsis])

Return type:

Tensor

classmethod mode(*params)

Abstractmethod:
Parameters:: params (Tensor)
Return type:: Tensor

Return the mode of the distribution (returning first value if discrete ties).

Parameters:

paramstorch.Tensor: The distribution parameters.

Returns:

torch.Tensor: The value of the distribution’s mode.

Parameters:

params (Tensor)

Return type:

Tensor

classmethod mean(nu, rho, xi, tau)

Return the mean of the distribution, if defined.

Parameters:

nutorch.Tensor
rhotorch.Tensor
xitorch.Tensor
tautorch.Tensor

Returns:

torch.Tensor: The value of the distribution’s mean.

Parameters:

nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)

Return type:

Tensor

classmethod stddev(nu, rho, xi, tau)

Return the standard-deviation of the distribution, given distribution parameters.

Parameters:

nutorch.Tensor
rhotorch.Tensor
xitorch.Tensor
tautorch.Tensor

Returns:

torch.Tensor: The value of the distribution’s standard deviation.

Parameters:

nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)

Return type:

Tensor

classmethod compute_log_likelihood_hazard(x, nu, rho, xi, tau, *params)

Parameters:

x (WeightedTensor)
nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)
params (Tensor)

Return type:

Tensor

classmethod compute_hazard(x, nu, rho, xi, tau, *params)

Parameters:

x (WeightedTensor)
nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)
params (Tensor)

Return type:

Tensor

classmethod compute_log_survival(x, nu, rho, xi, tau, *params)

Parameters:

x (Tensor)
nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)
params (Tensor)

Return type:

Tensor

classmethod compute_predictions(x, nu, rho, xi, tau, *params)

Parameters:

x (Tensor)
nu (Tensor)
rho (Tensor)
xi (Tensor)
tau (Tensor)
params (Tensor)

Return type:

Tensor

class WeibullRightCensoredFamily

Bases: AbstractWeibullRightCensoredFamily

Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).

TODO / WIP? allow WeightedTensor for parameters as well? (e.g. batched_deltas = Normal(batched_deltas_mean, …) which should be masked at some indices) –> mask at latent pop. variable level (batched_deltas) or

directly at model parameter level batched_deltas_mean?

parameters: ClassVar = ('nu', 'rho', 'xi', 'tau')

class WeibullRightCensoredWithSourcesFamily

Bases: AbstractWeibullRightCensoredFamily

Interface to represent stateless distribution families (i.e. no distribution parameters are stored in instance).

TODO / WIP? allow WeightedTensor for parameters as well? (e.g. batched_deltas = Normal(batched_deltas_mean, …) which should be masked at some indices) –> mask at latent pop. variable level (batched_deltas) or

directly at model parameter level batched_deltas_mean?

parameters: ClassVar = ('nu', 'rho', 'xi', 'tau', 'survival_shifts')

class SymbolicDistribution

Class providing symbolic methods for distribution families.

parameters_names: tuple[str, Ellipsis]

dist_family: Type[StatelessDistributionFamily]

validate_parameters: Callable[Ellipsis, tuple[Tensor, Ellipsis]]: Function of named distribution parameters, to validate these parameters.

shape: Callable[Ellipsis, tuple[int, Ellipsis]]: Function of named shapes of distribution parameters, to get shape of distribution samples.

mode: Callable[Ellipsis, Tensor]: Function of named distribution parameters, to get mode of distribution.

mean: Callable[Ellipsis, Tensor]: Function of named distribution parameters, to get mean of distribution.

stddev: Callable[Ellipsis, Tensor]: Function of named distribution parameters, to get std-deviation of distribution.

get_func(func, *extra_args_names, **kws)

Get keyword-only function from the stateless distribution family.

Parameters:

func (str)
extra_args_names (str)

get_func_sample(sample_shape=())

Factory of symbolic sampling function.

Parameters:

sample_shapetuple of int, optional: The shape of the sample. Default=().

Returns:

NamedInputFunction: The sample function.

Parameters:

sample_shape (tuple[int, Ellipsis])

Return type:

NamedInputFunction[Tensor]

get_func_regularization(value_name)

Factory of symbolic function: state -> negative log-likelihood of value.

Parameters:

value_namestr

Returns:

NamedInputFunction: The named input function to use to compute negative log likelihood.

Parameters:

value_name (str)

Return type:

NamedInputFunction[WeightedTensor[float]]

get_func_nll(value_name)

Factory of symbolic function: state -> negative log-likelihood of value.

Parameters:

value_namestr

Returns:

NamedInputFunction: The named input function to use to compute negative log likelihood.

Parameters:

value_name (str)

Return type:

NamedInputFunction[WeightedTensor[float]]

get_func_nll_jacobian(value_name)

Factory of symbolic function: state -> jacobian w.r.t. value of negative log-likelihood.

Parameters:

value_namestr

Returns:

NamedInputFunction: The named input function to use to compute negative log likelihood jacobian.

Parameters:

value_name (str)

Return type:

NamedInputFunction[WeightedTensor[float]]

get_func_nll_and_jacobian(value_name)

Factory of symbolic function: state -> (negative log-likelihood, its jacobian w.r.t. value).

Parameters:

value_namestr

Returns:

tuple [ NamedInputFunction, NamedInputFunction]: The named input functions to use to compute negative log likelihood and its jacobian.

Parameters:

value_name (str)

Return type:

NamedInputFunction[tuple[WeightedTensor[float], WeightedTensor[float]]]

classmethod bound_to(dist_family)

Return a factory to create SymbolicDistribution bound to the provided distribution family.

Parameters:

dist_familyStatelessDistributionFamily: The distribution family to use to create a SymbolicDistribution.

Returns:

factoryCallable[…, SymbolicDistribution]: The factory.

Parameters:

dist_family (Type[StatelessDistributionFamily])

Return type:

Callable[Ellipsis, SymbolicDistribution]

Normal

Bernoulli

WeibullRightCensored

WeibullRightCensoredWithSources