leaspy.models.utils.noise_model module

class NoiseModel(noise_struct: Optional[Union[NoiseStruct, str]], **noise_kws)

Bases: object

Helper class to define and work with different noise structures in models.

TODO? It may be of interest to define an abstract noise structure class with all methods needed to be transparently integrated in models and algorithms and then to create children classes of it (scalar gaussian, diagonal gaussian, more complex gaussian noise structures, Bernoulli realization, …)

Parameters

noise_structNoiseStruct, or str in VALID_NOISE_STRUCTS, or None

The noise structure to build noise model upon. If this is a string, noise structure will be searched among pre-defined noise structures:

• ‘bernoulli’: Bernoulli realization

• ‘gaussian_scalar’: Gaussian noise with scalar std-dev, to give as scale parameter

• ‘gaussian_diagonal’: Gaussian noise with 1 std-dev per feature (<!> order), to give as scale parameter

• ‘ordinal’: Samejima’s model for ordinal scales

If None: no noise at all (in particular, ultimately sample(r)_around(values) will just return values)

**noise_kws

Keyword arguments to fully characterize the noise structure. For now, only one parameter is supported, for Gaussian noise structures:

• scale (torch.FloatTensor): the std-dev requested for noise.

Raises

LeaspyInputError

If noise_struct is not supported.

See also

NoiseModel.from_model()

Attributes

structNoiseStruct

The noise structure, which contains its metadata / characteristics.

distributions_kwsdict[str, Any]

Extra keyword parameters to be passed to struct.distribution_factory apart the centering values.

Methods

check_compat_with_model(model)	Raise if noise_model is not compatible with model (consistency checks).
from_model(model[, noise_struct])	Initialize a noise model as in the from_name initialization but with special keywords so to easily inherit noise model from the one of an existing model.
get_named_noise_struct(name)	Helper to get a default noise structure from its name.
rmse_model(model, dataset, individual_params, *)	Helper function to compute the root mean square error (RMSE) from model reconstructions.
rv_around(loc)	Return the torch distribution centred around values (only if noise is not None).
sample_around(model_loc_values)	Realization around model_loc_values with respect to noise model.
sampler_around(loc)	Return the noise sampling function around input values.
set_noise_model_from_hyperparameters(model, ...)	Set noise_model of a model from hyperparameters.

OLD_MAPPING_FROM_LOSS = {'MSE': 'gaussian_scalar', 'MSE_diag_noise': 'gaussian_diagonal', 'crossentropy': 'bernoulli'}

VALID_NOISE_STRUCTS = {'bernoulli', 'gaussian_diagonal', 'gaussian_scalar', 'ordinal', 'ordinal_ranking'}

For backward-compatibility only.

check_compat_with_model(model: AbstractModel)

Raise if noise_model is not compatible with model (consistency checks).

classmethod from_model(model: AbstractModel, noise_struct: str = 'model', **noise_kws)

Initialize a noise model as in the from_name initialization but with special keywords so to easily inherit noise model from the one of an existing model.

It also automatically performs some consistency checks between model and noise parameters provided. As of now, it is mainly useful for simulation algorithm.

Parameters

modelAbstractModel, optional

The model you want to generate noise for. Only used when inheriting noise structure or to perform checks on Gaussian diagonal noise.

noise_structstr, optional (default ‘model’)

Noise structure requested. Multiple options:

• ‘model’: use the noise structure from model, as well as the noise parameters from model (if any)

• ‘inherit_struct’ (or deprecated ‘default’): use the noise structure from model provided

(but not the actual parameters of noise from model, if any) * All other regular noise structures supported (cf. class docstring)

**noise_kwsany

Extra parameters for noise (cf. class docstring) Not to be used when noise_struct = ‘model’ (default)

Returns

NoiseModel

classmethod get_named_noise_struct(name: Optional[str]) → NoiseStruct

Helper to get a default noise structure from its name.

static rmse_model(model: AbstractModel, dataset: Dataset, individual_params: DictParamsTorch, *, scalar: bool = None, **computation_kwargs) → torch.FloatTensor

Helper function to compute the root mean square error (RMSE) from model reconstructions.

Parameters

modelAbstractModel

Subclass object of AbstractModel.

datasetDataset

Dataset to compute reconstruction errors from.

individual_paramsDictParamsTorch

Object containing the computed individual parameters (torch format).

scalarbool or None (default)

Should we compute a scalar RMSE (averaged on all features) or one RMSE per feature (same order)? If None, it will fetch noise_model from model and choose scalar mode iif ‘scalar’ in noise_model string.

**computation_kwargs

Additional kwargs for model.compute_sum_squared_***_tensorized method

Returns

torch.FloatTensor

The RMSE tensor (1D) of length 1 if scalar else model.dimension.

rv_around(loc: FloatTensor) → Distribution

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

sample_around(model_loc_values: FloatTensor) → FloatTensor

Realization around model_loc_values with respect to noise model.

sampler_around(loc: FloatTensor) → Callable[[], FloatTensor]

Return the noise sampling function around input values.

property scale: Optional[FloatTensor]

A quick short-cut for scale of Gaussian noises (really useful??).

classmethod set_noise_model_from_hyperparameters(model, hyperparams: Dict[str, Any]) → Tuple[str, ...]

Set noise_model of a model from hyperparameters.

Parameters

modelAbstractModel

Where to set noise model (in-place)

hyperparamsdict[str, Any]

where to look for noise model

Returns

tuple[str]

Additional recognized hyperparameters for models.

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

Helper function to return a function returning the input value.