leaspy.models.utils.noise_struct module
- class MultinomialDistribution(sf: Tensor)
Bases:
Distribution
Class for a multinomial distribution with only sample method.
- Parameters
- sftorch.FloatTensor
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).
- Attributes
cdf
torch.FloatTensorReturns the cumulative density/mass function evaluated at value.
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)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.
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 = {}
- 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)
Generate a new MultinomialDistribution from its probability density function instead of its survival function.
- 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()
Multinomial sampling.
- Returns
- outtorch.IntTensor
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 (viapython -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: Optional[Any]
Returns a
Constraint
object representing this distribution’s support.
- validate_args = False
- property variance
Returns the variance of the distribution.
- class NoiseStruct(distribution_factory: ~typing.Optional[~typing.Callable[[...], ~torch.distributions.distribution.Distribution]] = None, model_kws_to_dist_kws: ~typing.Dict[str, str] = <factory>, dist_kws_validators: ~typing.Tuple[~typing.Callable[[~typing.Dict[str, ~typing.Any]], ~typing.Dict[str, ~typing.Any]], ...] = (), contextual_dist_kws_validators: ~typing.Tuple[~typing.Callable[[...], ~typing.Optional[~typing.Callable[[~typing.Dict[str, ~typing.Any]], ~typing.Dict[str, ~typing.Any]]]], ...] = ())
Bases:
object
Class storing all metadata of a noise structure (read-only).
This class is not intended to be used directly, it serves as configuration for NoiseModel helper class.
TODO? really have everything related to noise here, including stuff that is currently hardcoded in models (model log-likelihood…)?
- Parameters
- distribution_factoryfunction [torch.Tensor, **kws] -> torch.distributions.Distribution (or None)
A function taking a
torch.Tensor
of values first, possible keyword arguments and returning a noise generator (instance of classtorch.distributions.Distribution
), which can sample around these values with respect to noise structure.- model_kws_to_dist_kwsdict[str, str]
Mapping from naming of noise parameters in Leaspy model to the related torch distribution parameters.
- dist_kws_validatorstuple[ValidationFunc (kwargs -> kwargs)]
Tuple of functions that sequentially (FIFO) check (& possibly clean) distribution parameters (input). It may raise (LeaspyAlgoInputError) if those are not appropriate for the noise structure. Those validators are the ones that we already may define without any need for a context (e.g. a ‘gaussian_scalar’ noise will need the scale to be of dimension 1, always)
- contextual_dist_kws_validatorstuple[**context -> ValidationFunc or None]
Tuple of functions which are factory of validators functions, based on context parameters. Indeed, sometimes we may want to enforce some conditions, but we cannot enforce them without having extra contextual information (e.g. the scale of ‘gaussian_diagonal’ can be of any length in general, but if we already know the model dimension,
then we want to make sure that the scale parameter will be of the same dimension)
Note: if a given context is not sufficient to build a validator, factory should return None instead of a ValidationFunc. cf.
NoiseStruct.with_contextual_validators()
for more details.
- Attributes
dist_kws_to_model_kws
dict[str, str] (read-only property)Shortcut for reciprocal mapping of model_kws_to_dist_kws
- All the previous parameters are also attributes (dataclass)
Methods
validate_dist_kws
(dist_kws)Sequentially compose all validators to validate input.
with_contextual_validators
(**context_kws)Clone the current noise structure but with the additional contextual dist_kws_validators.
- contextual_dist_kws_validators: Tuple[Callable[[...], Optional[Callable[[Dict[str, Any]], Dict[str, Any]]]], ...] = ()
- property dist_kws_to_model_kws
Shortcut for reciprocal mapping of model_kws_to_dist_kws
- distribution_factory: Optional[Callable[[...], Distribution]] = None
- validate_dist_kws(dist_kws: Dict[str, Any]) Dict[str, Any]
Sequentially compose all validators to validate input.
- with_contextual_validators(**context_kws)
Clone the current noise structure but with the additional contextual dist_kws_validators.
Note: the contextual validators will be appended, in FIFO order, to the already existing dist_kws_validators (so in particular they will be executed after them).
- Parameters
- **context_kws
Any relevant keyword argument which may help to define additional contextual dist_kws_validators.
- Returns
- NoiseStruct
A cloned version of the current noise structure with relevant extra contextual validators set (they are now “static”, i.e. regular validators)
- check_scale_is_compat_with_model_dimension(*, model: AbstractModel, **unused_extra_kws)
Check that scale parameter is compatible with model dimension.
- check_scale_is_positive(d: Dict[str, Any])
Checks scale of noise is positive (component-wise if not scalar).
- convert_input_to_1D_float_tensors(d: Dict[str, Any]) Dict[str, FloatTensor]
Helper function to convert all input values into 1D torch float tensors.
- validate_dimension_of_scale_factory(error_tpl: str, expected_dim: int, *, klass=<class 'leaspy.exceptions.LeaspyInputError'>)
Helper to produce a validator function that check dimension of scale among parameters.