leaspy.models.noise_models module

class AbstractGaussianNoiseModel(parameters: Dict[str, Tensor] | None = None, scale_dimension: int | None = None)

Bases: GaussianFamily, BaseNoiseModel

Base class for Gaussian noise 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.
scale_dimensionint, optional: The scale dimension.

Attributes:

scale_dimensionint, optional: The scale dimension.
parametersdict: Contains the parameters relative to the noise model.
canonical_loss_propertiestuple: The properties for the canonical loss.

Methods

`compute_canonical_loss`(data, predictions)	Compute a human-friendly overall loss (RMSE).
`compute_l2_residuals`(data, predictions)	Compute the squared residuals of the given predictions.
`compute_nll`(data, predictions, *[, ...])	Negative log-likelihood without summation (and its gradient w.r.t.
`compute_residuals`(data, predictions)	Compute the residuals of the given predictions.
`compute_rmse`(data, predictions)	Computes root mean squared error of provided data vs.
`compute_sufficient_statistics`(data, predictions)	Compute the specific sufficient statistics and metrics for this noise-model.
`factory`	alias of `Normal`
`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, ...)	In-place update of free parameters from provided predictions.
`update_parameters_from_sufficient_statistics`(...)	In-place update of free parameters from provided sufficient statistics.
`validate`(**params)	Validation function for parameters (based on 'validate_xxx' methods).
`validate_scale`(scale)	Add a size-validation for scale parameter.

canonical_loss_properties: ClassVar = ('standard-deviation of the noise', '.2%')

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

Compute a human-friendly overall loss (RMSE).

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.

classmethod compute_l2_residuals(data: Dataset, predictions: Tensor) → Tensor

Compute the squared residuals of the given predictions.

Parameters:

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

Returns:

torch.Tensor: The squared residuals.

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

Negative log-likelihood without 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).

static compute_residuals(data: Dataset, predictions: Tensor) → Tensor

Compute the residuals of the given predictions.

Parameters:

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

Returns:

torch.Tensor: The residuals.

classmethod compute_rmse(data: Dataset, predictions: Tensor) → Tensor

Computes root mean squared error of provided data vs. predictions.

Parameters:

dataDataset: The dataset related to the computation of the root mean squared error.
predictionstorch.Tensor: The model’s predictions from which to compute the root mean squared error.

Returns:

torch.Tensor: The root mean squared error.

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

Compute the specific sufficient statistics and metrics for this noise-model.

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: alias of Normal

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

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: DictParamsTorch | 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.

scale_dimension: int | None = None

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

In-place update of free parameters from provided predictions.

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

In-place update of free parameters from provided sufficient statistics.

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.

validate_scale(scale: Tensor) → Tensor

Add a size-validation for scale parameter.

Parameters:

scaletorch.Tensor: The scale to validate.

Returns:

torch.Tensor: The validated scale.

class AbstractOrdinalNoiseModel(parameters: DictParamsTorch | None = None, max_levels: Dict[FeatureType, int] | None = None)

Bases: BaseNoiseModel

Base class for Ordinal noise 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.
max_levelsdict, optional: Maximum levels for ordinal noise.

Attributes:

max_levelsdict, optional: Maximum levels for ordinal noise.

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[..., torch.distributions.Distribution] | None]

free_parameters: ClassVar[FrozenSet[str]]

property mask

property max_level

max_levels: Dict[FeatureType, int] | None = None

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.

property ordinal_infos: Dict[str, Any]

parameters: DictParamsTorch | 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.

Warning

Do NOT export hyper-parameters that are derived (error-prone and boring checks when re-creating).

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 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[..., torch.distributions.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: DictParamsTorch | 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 BernoulliNoiseModel(parameters: Dict[str, Tensor] | None = None)

Bases: BernoulliFamily, BaseNoiseModel

Class implementing Bernoulli noise 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:

parameters

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 the negative log-likelihood and its gradient wrt predictions.
`compute_sufficient_statistics`(data, predictions)	Computes the set of noise-related sufficient statistics and metrics (to be extended in child class).
`factory`	alias of `Bernoulli`
`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.

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

Compute the negative log-likelihood and its gradient wrt predictions.

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: alias of Bernoulli

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: DictParamsTorch | 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 GaussianDiagonalNoiseModel(parameters: Dict[str, Tensor] | None = None, scale_dimension: int | None = None)

Bases: AbstractGaussianNoiseModel

Class implementing diagonal Gaussian noise 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.
scale_dimensionint, optional: The scale dimension.

Attributes:

scale_dimensionint, optional: The scale dimension.
parametersdict: Contains the parameters relative to the noise model.

Methods

`compute_canonical_loss`(data, predictions)	Compute a human-friendly overall loss (RMSE).
`compute_l2_residuals`(data, predictions)	Compute the squared residuals of the given predictions.
`compute_nll`(data, predictions, *[, ...])	Negative log-likelihood without summation (and its gradient w.r.t.
`compute_residuals`(data, predictions)	Compute the residuals of the given predictions.
`compute_rmse`(data, predictions)	Computes root mean squared error of provided data vs.
`compute_sufficient_statistics`(data, predictions)	Compute the specific sufficient statistics and metrics for this noise-model.
`factory`	alias of `Normal`
`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, ...)	In-place update of free parameters from provided predictions.
`update_parameters_from_sufficient_statistics`(...)	In-place update of free parameters from provided sufficient statistics.
`validate`(**params)	Validation function for parameters (based on 'validate_xxx' methods).
`validate_scale`(scale)	Ensure the scale is valid.

canonical_loss_properties: ClassVar = ('standard-deviation of the noise', '.2%')

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

Compute a human-friendly overall loss (RMSE).

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.

classmethod compute_l2_residuals(data: Dataset, predictions: Tensor) → Tensor

Compute the squared residuals of the given predictions.

Parameters:

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

Returns:

torch.Tensor: The squared residuals.

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

Negative log-likelihood without 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).

static compute_residuals(data: Dataset, predictions: Tensor) → Tensor

Compute the residuals of the given predictions.

Parameters:

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

Returns:

torch.Tensor: The residuals.

classmethod compute_rmse(data: Dataset, predictions: Tensor) → Tensor

Computes root mean squared error of provided data vs. predictions.

Parameters:

dataDataset: The dataset related to the computation of the root mean squared error.
predictionstorch.Tensor: The model’s predictions from which to compute the root mean squared error.

Returns:

torch.Tensor: The root mean squared error.

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

Compute the specific sufficient statistics and metrics for this noise-model.

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: alias of Normal

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

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: DictParamsTorch | 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.

scale_dimension: int | None = None

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

In-place update of free parameters from provided predictions.

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

In-place update of free parameters from provided sufficient statistics.

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.

validate_scale(scale: Tensor) → Tensor

Ensure the scale is valid.

Parameters:

scaletorch.Tensor: The scale to validate.

Returns:

torch.Tensor: The validated scale.

class GaussianScalarNoiseModel(parameters: Dict[str, Tensor] | None = None, scale_dimension: int | None = None)

Bases: AbstractGaussianNoiseModel

Class implementing scalar Gaussian noise models.

Parameters:

parametersdict [ :obj`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.
scale_dimensionint, optional: The scale dimension.

Attributes:

scale_dimensionint, optional: The scale dimension.
parametersdict: Contains the parameters relative to the noise model.

Methods

`compute_canonical_loss`(data, predictions)	Compute a human-friendly overall loss (RMSE).
`compute_l2_residuals`(data, predictions)	Compute the squared residuals of the given predictions.
`compute_nll`(data, predictions, *[, ...])	Negative log-likelihood without summation (and its gradient w.r.t.
`compute_residuals`(data, predictions)	Compute the residuals of the given predictions.
`compute_rmse`(data, predictions)	Computes root mean squared error of provided data vs.
`compute_sufficient_statistics`(data, predictions)	Compute the specific sufficient statistics and metrics for this noise-model.
`factory`	alias of `Normal`
`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, ...)	In-place update of free parameters from provided predictions.
`update_parameters_from_sufficient_statistics`(...)	In-place update of free parameters from provided sufficient statistics.
`validate`(**params)	Validation function for parameters (based on 'validate_xxx' methods).
`validate_scale`(scale)	Ensure the scale is valid.

canonical_loss_properties: ClassVar = ('standard-deviation of the noise', '.2%')

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

Compute a human-friendly overall loss (RMSE).

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.

classmethod compute_l2_residuals(data: Dataset, predictions: Tensor) → Tensor

Compute the squared residuals of the given predictions.

Parameters:

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

Returns:

torch.Tensor: The squared residuals.

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

Negative log-likelihood without 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).

static compute_residuals(data: Dataset, predictions: Tensor) → Tensor

Compute the residuals of the given predictions.

Parameters:

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

Returns:

torch.Tensor: The residuals.

classmethod compute_rmse(data: Dataset, predictions: Tensor) → Tensor

Computes root mean squared error of provided data vs. predictions.

Parameters:

dataDataset: The dataset related to the computation of the root mean squared error.
predictionstorch.Tensor: The model’s predictions from which to compute the root mean squared error.

Returns:

torch.Tensor: The root mean squared error.

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

Compute the specific sufficient statistics and metrics for this noise-model.

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: alias of Normal

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

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: DictParamsTorch | 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.

scale_dimension: int = 1

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

In-place update of free parameters from provided predictions.

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

In-place update of free parameters from provided sufficient statistics.

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.

validate_scale(scale: Tensor) → Tensor

Ensure the scale is valid.

Parameters:

scaletorch.Tensor: The scale to validate.

Returns:

torch.Tensor: The validated scale.

class OrdinalNoiseModel(parameters: DictParamsTorch | None = None, max_levels: Dict[FeatureType, int] | None = None)

Bases: OrdinalFamily, AbstractOrdinalNoiseModel

Class implementing ordinal noise models (likelihood is based on PDF).

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.
max_levelsdict, optional: Maximum levels for ordinal noise.

Attributes:

mask
max_level
max_levels
ordinal_infos
parameters

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 the negative log-likelihood and its gradient wrt predictions.
`compute_sufficient_statistics`(data, predictions)	Computes the set of noise-related sufficient statistics and metrics (to be extended in child class).
`factory`(pdf, **kws)	Generate a new MultinomialDistribution from its probability density function instead of its survival function.
`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.

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

Compute the negative log-likelihood and its gradient wrt predictions.

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.

classmethod factory(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.

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

property mask

property max_level

max_levels: Dict[FeatureType, int] | None = None

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.

property ordinal_infos: Dict[str, Any]

parameters: DictParamsTorch | 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.

Warning

Do NOT export hyper-parameters that are derived (error-prone and boring checks when re-creating).

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 OrdinalRankingNoiseModel(parameters: DictParamsTorch | None = None, max_levels: Dict[FeatureType, int] | None = None)

Bases: OrdinalRankingFamily, AbstractOrdinalNoiseModel

Class implementing OrdinalRankingNoiseModel (likelihood is based on SF).

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.
max_levelsdict, optional: Maximum levels for ordinal noise.

Attributes:

mask
max_level
max_levels
ordinal_infos
parameters

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 the negative log-likelihood and its gradient wrt predictions.
`compute_sufficient_statistics`(data, predictions)	Computes the set of noise-related sufficient statistics and metrics (to be extended in child class).
`factory`	alias of `MultinomialDistribution`
`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.

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

Compute the negative log-likelihood and its gradient wrt predictions.

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: alias of MultinomialDistribution

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

property mask

property max_level

max_levels: Dict[FeatureType, int] | None = None

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.

property ordinal_infos: Dict[str, Any]

parameters: DictParamsTorch | 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.

Warning

Do NOT export hyper-parameters that are derived (error-prone and boring checks when re-creating).

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.

export_noise_model(noise_model: BaseNoiseModel) → Dict[str, Any]

Serialize a given BaseNoiseModel as a dict.

Parameters:

noise_modelBaseNoiseModel: The noise model to serialize.

Returns:

KwargsType: The noise model serialized as a dict.

noise_model_factory(noise_model: str | BaseNoiseModel | Dict[str, Any], **kws) → BaseNoiseModel

Factory for noise models.

Parameters:

noise_modelstr or BaseNoiseModel or dict [ str, …]

If an instance of a subclass of BaseNoiseModel, returns the instance.
If a string, then returns a new instance of the appropriate class (with optional parameters kws).
If a dictionary, it must contain the ‘name’ key and other initialization parameters.

**kws

Optional parameters for initializing the requested noise-model when a string.

Returns:

BaseNoiseModel: The desired noise model.

Raises:

LeaspyModelInputError: If noise_model is not supported.