leaspy.utils.distributions module

Module defining useful distribution for ordinal noise model.

class MultinomialDistribution(sf: Tensor, *, validate_args: bool | None = True)

Bases: Distribution

Class for a multinomial distribution with only sample method.

Parameters:

sftorch.Tensor

Values of the survival function [P(X > l) for l=0..L-1 where L is max_level] from which the distribution samples. Ordinal levels are assumed to be in the last dimension. Those values must be in [0, 1], and decreasing when ordinal level increases (not checked).

validate_argsbool, optional (default True)

Whether to validate the arguments or not (None for default behavior, which changed after torch >= 1.8 to True).

Attributes:

cdftorch.Tensor

Returns the cumulative density/mass function evaluated at value.

arg_constraintsdict

Contains the constraints on the arguments.

Methods

cdf(value)	Returns the cumulative density/mass function evaluated at value.
entropy()	Returns entropy of distribution, batched over batch_shape.
enumerate_support([expand])	Returns tensor containing all values supported by a discrete distribution.
expand(batch_shape[, _instance])	Returns a new distribution instance (or populates an existing instance provided by a derived class) with batch dimensions expanded to batch_shape.
from_pdf(pdf, **kws)	Generate a new MultinomialDistribution from its probability density function instead of its survival function.
icdf(value)	Returns the inverse cumulative density/mass function evaluated at value.
log_prob(value)	Returns the log of the probability density/mass function evaluated at value.
perplexity()	Returns perplexity of distribution, batched over batch_shape.
rsample([sample_shape])	Generates a sample_shape shaped reparameterized sample or sample_shape shaped batch of reparameterized samples if the distribution parameters are batched.
sample()	Multinomial sampling.
sample_n(n)	Generates n samples or n batches of samples if the distribution parameters are batched.
set_default_validate_args(value)	Sets whether validation is enabled or disabled.

arg_constraints: ClassVar = {}

property batch_shape

Returns the shape over which parameters are batched.

cdf(value)

Returns the cumulative density/mass function evaluated at value.

Args:

value (Tensor):

entropy()

Returns entropy of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

enumerate_support(expand=True)

Returns tensor containing all values supported by a discrete distribution. The result will enumerate over dimension 0, so the shape of the result will be (cardinality,) + batch_shape + event_shape (where event_shape = () for univariate distributions).

Note that this enumerates over all batched tensors in lock-step [[0, 0], [1, 1], …]. With expand=False, enumeration happens along dim 0, but with the remaining batch dimensions being singleton dimensions, [[0], [1], ...

To iterate over the full Cartesian product use itertools.product(m.enumerate_support()).

Args:

expand (bool): whether to expand the support over the

batch dims to match the distribution’s batch_shape.

Returns:

Tensor iterating over dimension 0.

property event_shape

Returns the shape of a single sample (without batching).

expand(batch_shape, _instance=None)

Returns a new distribution instance (or populates an existing instance provided by a derived class) with batch dimensions expanded to batch_shape. This method calls expand on the distribution’s parameters. As such, this does not allocate new memory for the expanded distribution instance. Additionally, this does not repeat any args checking or parameter broadcasting in __init__.py, when an instance is first created.

Args:

batch_shape (torch.Size): the desired expanded size. _instance: new instance provided by subclasses that

need to override .expand.

Returns:

New distribution instance with batch dimensions expanded to batch_size.

classmethod from_pdf(pdf: Tensor, **kws)

Generate a new MultinomialDistribution from its probability density function instead of its survival function.

Parameters:

pdftorch.Tensor

The input probability density function.

**kws

Additional keyword arguments to be passed for instance initialization.

has_enumerate_support = False

has_rsample = False

icdf(value)

Returns the inverse cumulative density/mass function evaluated at value.

Args:

value (Tensor):

log_prob(value)

Returns the log of the probability density/mass function evaluated at value.

Args:

value (Tensor):

property mean

Returns the mean of the distribution.

perplexity()

Returns perplexity of distribution, batched over batch_shape.

Returns:

Tensor of shape batch_shape.

rsample(sample_shape=torch.Size([]))

Generates a sample_shape shaped reparameterized sample or sample_shape shaped batch of reparameterized samples if the distribution parameters are batched.

sample() → Tensor

Multinomial sampling.

We sample uniformly on [0, 1( but for the latest dimension corresponding to ordinal levels this latest dimension will be broadcast when comparing with cdf.

Returns:

torch.Tensor

Vector of integer values corresponding to the multinomial sampling. Result is in [[0, L]]

sample_n(n)

Generates n samples or n batches of samples if the distribution parameters are batched.

static set_default_validate_args(value)

Sets whether validation is enabled or disabled.

The default behavior mimics Python’s assert statement: validation is on by default, but is disabled if Python is run in optimized mode (via python -O). Validation may be expensive, so you may want to disable it once a model is working.

Args:

value (bool): Whether to enable validation.

property stddev

Returns the standard deviation of the distribution.

property support: Any | None

Returns a Constraint object representing this distribution’s support.

property variance

Returns the variance of the distribution.

discrete_sf_from_pdf(pdf: Tensor | ndarray) → Tensor

Compute the discrete survival function values [P(X > l), i.e. P(X >= l+1), l=0..L-1] (l=0..L-1) from the discrete probability density [P(X = l), l=0..L] (assuming discrete levels are in last dimension).

Parameters:

pdftorch.Tensor or np.ndarray

The discrete probability density.

Returns:

np.ndarray

The discrete survival function values.