leaspy.variables.specs

Attributes

`VariableName`
`VariableValue`
`VariableNameToValueMapping`
`VariablesToFrozenSet`
`VariablesLazyValuesRO`
`VariablesLazyValuesRW`
`SuffStatsRO`
`SuffStatsRW`

Classes

`VariableInterface`	Interface for variable specifications.
`IndepVariable`	Base class for variable that is not dependent on any other variable.
`Hyperparameter`	Hyperparameters that can not be reset.
`Collect`	A convenient class to produce a function to collect sufficient stats that are existing or dedicated variables (to be automatically created).
`ModelParameter`	Variable for model parameters with a maximization rule. This variable shouldn't be sampled and it shouldn't be data, a hyperparameter or a linked variable.
`DataVariable`	Variables for input data, that may be reset.
`LatentVariableInitType`	Type of initialization for latent variables.
`LatentVariable`	Unobserved variable that will be sampled, with symbolic prior distribution [e.g. Normal('xi_mean', 'xi_std')].
`PopulationLatentVariable`	Population latent variable.
`IndividualLatentVariable`	Individual latent variable.
`LinkedVariable`	Variable which is a deterministic expression of other variables (we directly use variables names instead of mappings: kws <-> vars).
`NamedVariables`	Convenient dictionary for named variables specifications.

Module Contents

VariableName

VariableValue

VariableNameToValueMapping

VariablesToFrozenSet

VariablesLazyValuesRO

VariablesLazyValuesRW

SuffStatsRO

SuffStatsRW

class VariableInterface

Interface for variable specifications.

is_settable: ClassVar[bool]: Is True if and only if state of variables is intended to be manually modified by user.

fixed_shape: ClassVar[bool]: Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data.

abstractmethod compute(state)

Compute variable value from a state exposing a dict-like interface: var_name -> values.

If not relevant for variable type return None.

Parameters:

stateVariableNameToValueMapping: The state to use in order to perform computations.

Returns:

VariableValue: The variable value computed from the state.

Parameters:

state (VariableNameToValueMapping)

Return type:

Optional[VariableValue]

abstractmethod get_ancestors_names()

Get the names of the variables that the current variable directly depends on.

Returns:

frozenset [ VariableName]: The set of ancestors variable names.

Return type:

frozenset[VariableName]

class IndepVariable

Bases: VariableInterface

Base class for variable that is not dependent on any other variable.

get_ancestors_names()

Get the names of the variables that the current variable directly depends on.

Returns:

frozenset [ VariableName]: The set of ancestors variable names.

Return type:

frozenset[VariableName]

compute(state)

Compute variable value from a state exposing a dict-like interface: var_name -> values.

If not relevant for variable type return None.

Parameters:

stateVariableNameToValueMapping: The state to use in order to perform computations.

Returns:

VariableValue or None:: The variable value computed from the state.

Parameters:

state (VariableNameToValueMapping)

Return type:

Optional[VariableValue]

class Hyperparameter

Bases: IndepVariable

Hyperparameters that can not be reset.

value: VariableValue: The hyperparameter value.

fixed_shape: ClassVar = True: Whether the variable has a fixed shape or not. For hyperparameters this is True.

is_settable: ClassVar = False: Whether the variable is mutable or not. For hyperparameters this is False.

to_device(device)

Move the value to specified device (other variables never hold values so need for this method).

Parameters:

devicetorch.device: The device on which to move the variable value.

Parameters:

device (device)

Return type:

None

property shape: tuple[int, Ellipsis]

Return type:: tuple[int, Ellipsis]

class Collect(*existing_variables, **dedicated_variables)

A convenient class to produce a function to collect sufficient stats that are existing or dedicated variables (to be automatically created).

Parameters:

existing_variables (VariableName)
dedicated_variables (LinkedVariable)

existing_variables: tuple[VariableName, Ellipsis] = ()

dedicated_variables: Mapping[VariableName, LinkedVariable] | None = None

property variables: tuple[VariableName, Ellipsis]

Return type:: tuple[VariableName, Ellipsis]

class ModelParameter

Bases: IndepVariable

Variable for model parameters with a maximization rule. This variable shouldn’t be sampled and it shouldn’t be data, a hyperparameter or a linked variable.

shape: tuple[int, Ellipsis]

suff_stats: Collect

The symbolic update functions will take variadic suff_stats values, in order to re-use NamedInputFunction logic: e.g. update_rule=Std(‘xi’)

<!> ISSUE: for tau_std and xi_std we also need state values in addition to suff_stats values (only after burn-in) since we can NOT use the variadic form readily for both state and suff_stats (names would be conflicting!), we sent state as a special kw variable (a bit lazy but valid) (and we prevent using this name for a variable as a safety)

update_rule: Callable[Ellipsis, VariableValue]: Update rule for normal phase, and memory-less (burn-in) phase unless update_rule_burn_in is not None.

update_rule_burn_in: Callable[Ellipsis, VariableValue] | None = None: Specific rule for burn-in (currently implemented for some variables -> e.g. xi_std)

fixed_shape: ClassVar = True: Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data.

is_settable: ClassVar = True: Is True if and only if state of variables is intended to be manually modified by user.

compute_update(*, state, suff_stats, burn_in)

Compute the updated value for the model parameter using a maximization step.

Parameters:

stateVariableNameToValueMapping: The state to use for computations.
suff_statsSuffStatsRO: The sufficient statistics to use.
burn_inbool: If True, use the update rule in burning phase.

Returns:

VariableValue: The computed variable value.

Parameters:

state (VariableNameToValueMapping)
suff_stats (SuffStatsRO)
burn_in (bool)

Return type:

VariableValue

classmethod for_pop_mean(population_variable_name, shape)

Smart automatic definition of ModelParameter when it is the mean of Gaussian prior of a population latent variable.

Parameters:

population_variable_name (VariableName)
shape (tuple[int, Ellipsis])

classmethod for_ind_mean(individual_variable_name, shape)

Smart automatic definition of ModelParameter when it is the mean of Gaussian prior of an individual latent variable.

Parameters:

individual_variable_name (VariableName)
shape (tuple[int, Ellipsis])

classmethod for_ind_std(individual_variable_name, shape, **tol_kw)

Smart automatic definition of ModelParameter when it is the std-dev of Gaussian prior of an individual latent variable.

Parameters:

individual_variable_name (VariableName)
shape (tuple[int, Ellipsis])

class DataVariable

Bases: IndepVariable

Variables for input data, that may be reset.

fixed_shape: ClassVar = False: Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data.

is_settable: ClassVar = True: Is True if and only if state of variables is intended to be manually modified by user.

class LatentVariableInitType

Bases: str, enum.Enum

Type of initialization for latent variables.

PRIOR_MODE = 'mode'

PRIOR_MEAN = 'mean'

PRIOR_SAMPLES = 'samples'

class LatentVariable

Bases: IndepVariable

Unobserved variable that will be sampled, with symbolic prior distribution [e.g. Normal(‘xi_mean’, ‘xi_std’)].

prior: SymbolicDistribution

sampling_kws: leaspy.utils.typing.KwargsType | None = None

is_settable: ClassVar = True: Is True if and only if state of variables is intended to be manually modified by user.

get_prior_shape(named_vars)

Get shape of prior distribution (i.e. without any expansion for IndividualLatentVariable).

Parameters:: named_vars (Mapping[VariableName, VariableInterface])
Return type:: tuple[int, Ellipsis]

abstractmethod get_regularity_variables(value_name)

Get extra linked variables to compute regularity term for this latent variable.

Parameters:: value_name (VariableName)
Return type:: dict[VariableName, LinkedVariable]

class PopulationLatentVariable

Bases: LatentVariable

Population latent variable.

fixed_shape: ClassVar = True: Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data.

get_init_func(method)

Return a NamedInputFunction: State -> Tensor, that may be used for initialization.

Parameters:

methodLatentVariableInitType or str: The method to be used.

Returns:

NamedInputFunction: The initialization function.

Parameters:

method (Union[str, LatentVariableInitType])

Return type:

NamedInputFunction[Tensor]

get_regularity_variables(variable_name)

Return the negative log likelihood regularity for the provided variable name.

Parameters:

variable_nameVariableName: The name of the variable for which to retrieve regularity.

Returns:

dict [ VariableName, LinkedVariable]: The dictionary holding the LinkedVariable for the regularity.

Parameters:

variable_name (VariableName)

Return type:

dict[VariableName, LinkedVariable]

class IndividualLatentVariable

Bases: LatentVariable

Individual latent variable.

fixed_shape: ClassVar = False: Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data.

get_init_func(method, *, n_individuals)

Return a NamedInputFunction: State -> Tensor, that may be used for initialization.

Parameters:

methodLatentVariableInitType or str: The method to be used.
n_individualsint: The number of individuals, used to define the shape.

Returns:

NamedInputFunction: The initialization function.

Parameters:

method (Union[str, LatentVariableInitType])
n_individuals (int)

Return type:

NamedInputFunction[Tensor]

get_regularity_variables(variable_name)

Return the negative log likelihood regularity for the provided variable name.

Parameters:

variable_nameVariableName: The name of the variable for which to retrieve regularity.

Returns:

dict [ VariableName, LinkedVariable]: The dictionary holding the LinkedVariable for the regularity.

Parameters:

variable_name (VariableName)

Return type:

dict[VariableName, LinkedVariable]

class LinkedVariable

Bases: VariableInterface

Variable which is a deterministic expression of other variables (we directly use variables names instead of mappings: kws <-> vars).

f: Callable[Ellipsis, VariableValue]

parameters: frozenset[VariableName]

is_settable: ClassVar = False: Is True if and only if state of variables is intended to be manually modified by user.

fixed_shape: ClassVar = False: Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data.

get_ancestors_names()

Get the names of the variables that the current variable directly depends on.

Returns:

frozenset [ VariableName]: The set of ancestors variable names.

Return type:

frozenset[VariableName]

compute(state)

Compute the variable value from a given State.

Parameters:

stateVariableNameToValueMapping: The state to use for computations.

Returns:

VariableValue: The value of the variable.

Parameters:

state (VariableNameToValueMapping)

Return type:

VariableValue

class NamedVariables(*args, **kws)

Bases: collections.UserDict

Convenient dictionary for named variables specifications.

In particular, it:

forbids the collisions in variable names when assigning/updating the collection
forbids the usage of some reserved names like ‘state’ or ‘suff_stats’
automatically adds implicit variables when variables of certain kind are added (e.g. dedicated vars for sufficient stats of ModelParameter)
automatically adds summary variables depending on all contained variables (e.g. nll_regul_ind_sum that depends on all individual latent variables contained)

<!> For now, you should NOT update a NamedVariables with another one, only update with a regular mapping.

FORBIDDEN_NAMES: ClassVar

AUTOMATIC_VARS: ClassVar = ('nll_regul_ind_sum_ind', 'nll_regul_ind_sum')