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:
- parameters
dict
[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.
- parameters
- Attributes:
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 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).
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:
- data
Dataset
The dataset related to the computation of the log likelihood.
- predictions
torch.Tensor
The model’s predictions from which to compute the canonical loss.
- data
- 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:
- data
Dataset
The dataset related to the computation of the log likelihood.
- predictions
torch.Tensor
The model’s predictions from which to compute the log likelihood.
- with_gradient
bool
, 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.
- data
- Returns:
torch.Tensor
ortuple
oftorch.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:
- data
Dataset
The dataset related to the computation of the sufficient statistics.
- predictions
torch.Tensor
The model’s predictions from which to compute the sufficient statistics.
- data
- Returns:
DictParamsTorch
The sufficient statistics.
- move_to_device(device: device) None
Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
- Parameters:
- device
torch.device
Torch device on which to move the tensors.
- device
- 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:
- loc
torch.Tensor
The loc around which to sample.
- loc
- 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:
- loc
torch.Tensor
The loc around which to sample.
- loc
- Returns:
torch.Tensor
The requested sample.
- sampler_around(loc: Tensor) Callable[[], Tensor]
Return the sampling function around input values.
- Parameters:
- loc
torch.Tensor
The loc around which to sample.
- loc
- 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:
- validate
bool
, optional If True, the provided parameters are validated before being updated. Default=False.
- **parameters
torch.Tensor
The new parameters.
- validate
- update_parameters_from_predictions(data: Dataset, predictions: Tensor) None
Updates noise-model parameters in-place (nothing done by default).
- Parameters:
- data
Dataset
The dataset related to the computation of the log likelihood.
- predictions
torch.Tensor
The model’s predictions from which to update the parameters.
- data
- update_parameters_from_sufficient_statistics(data: Dataset, sufficient_statistics: Dict[str, Tensor]) None
Updates noise-model parameters in-place (nothing done by default).
- Parameters:
- data
Dataset
The dataset related to the computation of the log likelihood.
- sufficient_statistics
DictParamsTorch
The sufficient statistics to use for parameter update.
- data
- 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:
- parameters
dict
[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.
- parameters
- Attributes:
- free_parameters
frozenset
ofstr
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.
- parameters
dict
[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.
- free_parameters
Methods
move_to_device
(device)Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
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]
- move_to_device(device: device) None
Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
- Parameters:
- device
torch.device
Torch device on which to move the tensors.
- device
- 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:
- loc
torch.Tensor
The loc around which to sample.
- loc
- 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:
- loc
torch.Tensor
The loc around which to sample.
- loc
- Returns:
torch.Tensor
The requested sample.
- sampler_around(loc: Tensor) Callable[[], Tensor]
Return the sampling function around input values.
- Parameters:
- loc
torch.Tensor
The loc around which to sample.
- loc
- 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:
- validate
bool
, optional If True, the provided parameters are validated before being updated. Default=False.
- **parameters
torch.Tensor
The new parameters.
- validate
- 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:
- parameters
dict
[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.
- parameters
- Attributes:
- free_parameters
frozenset
ofstr
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.
- free_parameters
Methods
move_to_device
(device)Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
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
- move_to_device(device: device) None
Move all torch tensors stored in this instance to the provided device (parameters & hyperparameters).
- Parameters:
- device
torch.device
Torch device on which to move the tensors.
- device
- 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:
- loc
torch.Tensor
The loc around which to sample.
- loc
- 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:
- loc
torch.Tensor
The loc around which to sample.
- loc
- Returns:
torch.Tensor
The requested sample.
- sampler_around(loc: Tensor) Callable[[], Tensor]
Return the sampling function around input values.
- Parameters:
- loc
torch.Tensor
The loc around which to sample.
- loc
- 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:
- validate
bool
, optional If True, the provided parameters are validated before being updated. Default=False.
- **parameters
torch.Tensor
The new parameters.
- validate
- 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.