leaspy.models.noise_models.base module

BaseNoiseModel defines the common interface for noise models in Leaspy.

class BaseNoiseModel(parameters: Dict[str, Tensor] | None = None)

Bases: ABC, DistributionFamily

Base class for valid noise models that may be used in probabilistic models.

The negative log-likelihood (nll, to be minimized) always corresponds to attachment term in models.

Parameters:

parametersdict [ str, torch.Tensor ] or None: Values for all the free parameters of the distribution family. All of them must have values before using the sampling methods.

Attributes:

parametersdict [ str, torch.Tensor ] or None: All values for the free parameters of the distribution family. None is to be used if and only if there are no free_parameters at all.
canonical_loss_propertiestuple [ str, str ]: Tuple of strings characterizing the canonical loss of the noise model.

Methods

`compute_canonical_loss`(data, predictions)	Compute a human-friendly overall loss (independent from instance parameters), useful as a measure of goodness-of-fit after personalization (nll by default - assuming no free parameters).
`compute_nll`(data, predictions, *[, ...])	Compute negative log-likelihood of data given model predictions (no summation), and its gradient w.r.t.
`compute_sufficient_statistics`(data, predictions)	Computes the set of noise-related sufficient statistics and metrics (to be extended in child class).
`move_to_device`(device)	Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
`raise_if_partially_defined`()	Raise an error if some of the free parameters are not defined.
`raise_if_unknown_parameters`(params)	Raise an error if the provided parameters are not part of the free parameters.
`rv_around`(loc)	Return the torch distribution centred around values (only if noise is not None).
`sample_around`(loc)	Realization around loc with respect to partially defined distribution.
`sampler_around`(loc)	Return the sampling function around input values.
`to_dict`()	Serialize instance as dictionary.
`update_parameters`(*[, validate])	(Partial) update of the free parameters of the distribution family.
`update_parameters_from_predictions`(data, ...)	Updates noise-model parameters in-place (nothing done by default).
`update_parameters_from_sufficient_statistics`(...)	Updates noise-model parameters in-place (nothing done by default).
`validate`(**params)	Validation function for parameters (based on 'validate_xxx' methods).

canonical_loss_properties: ClassVar = ('(neg) log-likelihood for attachment', '.3f')

compute_canonical_loss(data: Dataset, predictions: Tensor) → Tensor

Compute a human-friendly overall loss (independent from instance parameters), useful as a measure of goodness-of-fit after personalization (nll by default - assuming no free parameters).

Parameters:

dataDataset: The dataset related to the computation of the log likelihood.
predictionstorch.Tensor: The model’s predictions from which to compute the canonical loss.

Returns:

torch.Tensor: The computed loss.

abstract compute_nll(data: Dataset, predictions: Tensor, *, with_gradient: bool = False) → Tensor | Tuple[Tensor, Tensor]

Compute negative log-likelihood of data given model predictions (no summation), and its gradient w.r.t. predictions if requested.

Parameters:

dataDataset: The dataset related to the computation of the log likelihood.
predictionstorch.Tensor: The model’s predictions from which to compute the log likelihood.
with_gradientbool, optional: If True, returns also the gradient of the negative log likelihood wrt the predictions. If False, only returns the negative log likelihood. Default=False.

Returns:

torch.Tensor or tuple of torch.Tensor: The negative log likelihood (and its jacobian if requested).

compute_sufficient_statistics(data: Dataset, predictions: Tensor) → Dict[str, Tensor]

Computes the set of noise-related sufficient statistics and metrics (to be extended in child class).

Parameters:

dataDataset: The dataset related to the computation of the sufficient statistics.
predictionstorch.Tensor: The model’s predictions from which to compute the sufficient statistics.

Returns:

DictParamsTorch: The sufficient statistics.

factory: ClassVar[Callable[[...], Distribution] | None]

free_parameters: ClassVar[FrozenSet[str]]

move_to_device(device: device) → None

Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).

Parameters:

devicetorch.device: Torch device on which to move the tensors.

parameters: Dict[str, Tensor] | None = None

raise_if_partially_defined() → None: Raise an error if some of the free parameters are not defined.

classmethod raise_if_unknown_parameters(params: Iterable | None) → None

Raise an error if the provided parameters are not part of the free parameters.

Parameters:

paramsIterable, optional: The list of parameters to analyze.

rv_around(loc: Tensor) → Distribution

Return the torch distribution centred around values (only if noise is not None).

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

torch.distributions.distribution.Distribution: The torch distribution centered around the loc.

sample_around(loc: Tensor) → Tensor

Realization around loc with respect to partially defined distribution.

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

torch.Tensor: The requested sample.

sampler_around(loc: Tensor) → Callable[[], Tensor]

Return the sampling function around input values.

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

Callable: The sampler.

to_dict() → Dict[str, Any]

Serialize instance as dictionary.

Returns:

KwargsType: The instance serialized as a dictionary.

update_parameters(*, validate: bool = False, **parameters: Tensor) → None

(Partial) update of the free parameters of the distribution family.

Parameters:

validatebool, optional: If True, the provided parameters are validated before being updated. Default=False.
**parameterstorch.Tensor: The new parameters.

update_parameters_from_predictions(data: Dataset, predictions: Tensor) → None

Updates noise-model parameters in-place (nothing done by default).

Parameters:

dataDataset: The dataset related to the computation of the log likelihood.
predictionstorch.Tensor: The model’s predictions from which to update the parameters.

update_parameters_from_sufficient_statistics(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Updates noise-model parameters in-place (nothing done by default).

Parameters:

dataDataset: The dataset related to the computation of the log likelihood.
sufficient_statisticsDictParamsTorch: The sufficient statistics to use for parameter update.

validate(**params: Any) → Dict[str, Tensor]

Validation function for parameters (based on ‘validate_xxx’ methods).

Parameters:

**paramsAny: The parameters to validate.

Returns:

DictParamsTorch: The validated parameters.

class DistributionFamily(parameters: Dict[str, Tensor] | None = None)

Bases: object

Base class for a distribution family being able to sample “around” user-provided values.

Parameters:

parametersdict [ str, torch.Tensor ] or None: Values for all the free parameters of the distribution family. All of them must have values before using the sampling methods.

Attributes:

free_parametersfrozenset of str: Name of all the free parameters (but loc) needed to characterize the distribution. Nota: for each parameter, if a method named “validate_xxx” exists (torch.Tensor -> torch.Tensor), then it will be used for user-input validation of parameter “xxx”.
factoryNone or function(free parameters values) -> torch.distributions.distribution.Distribution: The factory for the distribution family.
parametersdict [ str, torch.Tensor ] or None: Values for all the free parameters of the distribution family. All of them must have values before using the sampling methods.

Methods

`move_to_device`(device)	Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
`raise_if_partially_defined`()	Raise an error if some of the free parameters are not defined.
`raise_if_unknown_parameters`(params)	Raise an error if the provided parameters are not part of the free parameters.
`rv_around`(loc)	Return the torch distribution centred around values (only if noise is not None).
`sample_around`(loc)	Realization around loc with respect to partially defined distribution.
`sampler_around`(loc)	Return the sampling function around input values.
`to_dict`()	Serialize instance as dictionary.
`update_parameters`(*[, validate])	(Partial) update of the free parameters of the distribution family.
`validate`(**params)	Validation function for parameters (based on 'validate_xxx' methods).

factory: ClassVar[Callable[[...], Distribution] | None]

free_parameters: ClassVar[FrozenSet[str]]

move_to_device(device: device) → None

Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).

Parameters:

devicetorch.device: Torch device on which to move the tensors.

parameters: Dict[str, Tensor] | None = None

raise_if_partially_defined() → None: Raise an error if some of the free parameters are not defined.

classmethod raise_if_unknown_parameters(params: Iterable | None) → None

Raise an error if the provided parameters are not part of the free parameters.

Parameters:

paramsIterable, optional: The list of parameters to analyze.

rv_around(loc: Tensor) → Distribution

Return the torch distribution centred around values (only if noise is not None).

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

torch.distributions.distribution.Distribution: The torch distribution centered around the loc.

sample_around(loc: Tensor) → Tensor

Realization around loc with respect to partially defined distribution.

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

torch.Tensor: The requested sample.

sampler_around(loc: Tensor) → Callable[[], Tensor]

Return the sampling function around input values.

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

Callable: The sampler.

to_dict() → Dict[str, Any]

Serialize instance as dictionary.

Returns:

KwargsType: The instance serialized as a dictionary.

update_parameters(*, validate: bool = False, **parameters: Tensor) → None

(Partial) update of the free parameters of the distribution family.

Parameters:

validatebool, optional: If True, the provided parameters are validated before being updated. Default=False.
**parameterstorch.Tensor: The new parameters.

validate(**params: Any) → Dict[str, Tensor]

Validation function for parameters (based on ‘validate_xxx’ methods).

Parameters:

**paramsAny: The parameters to validate.

Returns:

DictParamsTorch: The validated parameters.

class NoNoise(parameters: Dict[str, Tensor] | None = None)

Bases: DistributionFamily

A dummy noise model that only returns the provided values.

This model may be useful for simulation.

Parameters:

parametersdict [ str, torch.Tensor ] or None: Values for all the free parameters of the distribution family. All of them must have values before using the sampling methods.

Attributes:

free_parametersfrozenset of str: Name of all the free parameters (but loc) needed to characterize the distribution. Nota: for each parameter, if a method named “validate_xxx” exists (torch.Tensor -> torch.Tensor), then it will be used for user-input validation of parameter “xxx”.
factoryNone or function(free parameters values) -> torch.distributions.distribution.Distribution: The factory for the distribution family.

Methods

`move_to_device`(device)	Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
`raise_if_partially_defined`()	Raise an error if some of the free parameters are not defined.
`raise_if_unknown_parameters`(params)	Raise an error if the provided parameters are not part of the free parameters.
`rv_around`(loc)	Return the torch distribution centred around values (only if noise is not None).
`sample_around`(loc)	Realization around loc with respect to partially defined distribution.
`sampler_around`(loc)	Return the sampling function around input values.
`to_dict`()	Serialize instance as dictionary.
`update_parameters`(*[, validate])	(Partial) update of the free parameters of the distribution family.
`validate`(**params)	Validation function for parameters (based on 'validate_xxx' methods).

factory: ClassVar[Callable[[...], Distribution] | None] = None

free_parameters: ClassVar[FrozenSet[str]] = frozenset({})

move_to_device(device: device) → None

Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).

Parameters:

devicetorch.device: Torch device on which to move the tensors.

parameters: Dict[str, Tensor] | None = None

raise_if_partially_defined() → None: Raise an error if some of the free parameters are not defined.

classmethod raise_if_unknown_parameters(params: Iterable | None) → None

Raise an error if the provided parameters are not part of the free parameters.

Parameters:

paramsIterable, optional: The list of parameters to analyze.

rv_around(loc: Tensor) → Distribution

Return the torch distribution centred around values (only if noise is not None).

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

torch.distributions.distribution.Distribution: The torch distribution centered around the loc.

sample_around(loc: Tensor) → Tensor

Realization around loc with respect to partially defined distribution.

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

torch.Tensor: The requested sample.

sampler_around(loc: Tensor) → Callable[[], Tensor]

Return the sampling function around input values.

Parameters:

loctorch.Tensor: The loc around which to sample.

Returns:

Callable: The sampler.

to_dict() → Dict[str, Any]

Serialize instance as dictionary.

Returns:

KwargsType: The instance serialized as a dictionary.

update_parameters(*, validate: bool = False, **parameters: Tensor) → None

(Partial) update of the free parameters of the distribution family.

Parameters:

validatebool, optional: If True, the provided parameters are validated before being updated. Default=False.
**parameterstorch.Tensor: The new parameters.

validate(**params: Any) → Dict[str, Tensor]

Validation function for parameters (based on ‘validate_xxx’ methods).

Parameters:

**paramsAny: The parameters to validate.

Returns:

DictParamsTorch: The validated parameters.

constant_return_factory(x: T) → Callable[[], T]

Return a function returning the input value.

Parameters:

xT: The input value.

Returns:

Callable: The constant return factory.

value_to_tensor(x: Any) → Tensor

Transform input values to tensors.

Not intended to be used on values not castable to tensors, e.g. None.

Parameters:

xAny: The value that should be converted to a tensor.

Returns:

torch.Tensor: The value converted to a tensor.