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
`ModelParameter`	Variable for model parameters with a maximization rule. This variable shouldn't
`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.
`PopulationLatentVariable`	Population latent variable.
`IndividualLatentVariable`	Individual latent variable.
`LinkedVariable`	Variable which is a deterministic expression of other variables
`NamedVariables`	Convenient dictionary for named variables specifications.

Module Contents¶

VariableName¶

VariableValue¶

VariableNameToValueMapping¶

VariablesToFrozenSet¶

VariablesLazyValuesRO¶

VariablesLazyValuesRW¶

SuffStatsRO¶

SuffStatsRW¶

class VariableInterface[source]¶

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)[source]¶

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()[source]¶

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[source]¶

Bases: VariableInterface

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

get_ancestors_names()[source]¶

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)[source]¶

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[source]¶

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)[source]¶

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)[source]¶

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

Parameters:

existing_variablestuple of VariableName, optional: Names of existing variables that should be included when collecting statistics.
dedicated_variablesdict [VariableName, LinkedVariable], optional: Custom or derived variables that will be included in the collection process.

Parameters:

existing_variables (VariableName)
dedicated_variables (LinkedVariable)

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

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

property variables: tuple[VariableName, Ellipsis]¶

Get the combined list of all variable names to be collected.

Returns:

tuple of VariableName: Tuple containing both existing and dedicated variable names.

Return type:

tuple[VariableName, Ellipsis]

class ModelParameter[source]¶

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.

Parameters:

shapetuple of int: Shape of the parameter tensor. It must be fixed and known in advance.
suff_statsCollect: A callable object that collects sufficient statistics required to compute the update.
update_ruletyping.Callable […, VariableValue]: The symbolic update rule for this parameter, used during both burn-in and standard learning phase unless overridden by update_rule_burn_in.
update_rule_burn_intyping.Callable […, VariableValue] or None, optional: An optional alternative update rule specifically used during the burn-in phase. If provided, it overrides update_rule during that phase.

Attributes:

_update_rule_parametersfrozenset of VariableName: Internal cache of variable names required by update_rule.
_update_rule_burn_in_parametersfrozenset of VariableName or None: Internal cache of variable names required by update_rule_burn_in, if defined.
fixed_shapebool (class attribute): Indicates that this variable has a fixed shape (True by design).
is_settablebool (class attribute): Flags this variable as being settable externally (True by design).

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)[source]¶

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)[source]¶

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

Parameters:

population_variable_nameVariableName: Name of the population latent variable for which this is the prior mean.
shapetuple of int: The shape of the model parameter (typically matching the variable’s dimensionality).

Returns:

ModelParameter: A new instance of ModelParameter configured as a prior mean.

Parameters:

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

classmethod for_ind_mean(individual_variable_name, shape)[source]¶

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

Parameters:

individual_variable_nameVariableName: Name of the individual latent variable for which this is the prior mean.
shapetuple of int: The shape of the model parameter (typically matching the variable’s dimensionality).

Returns:

ModelParameter: A new instance of ModelParameter configured as a prior mean.

Parameters:

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

classmethod for_ind_mean_mixture(ind_var_name, shape)[source]¶

Smart automatic definition of ModelParameter when it is the mean of a mixture of Gaussians prior of an individual latent variable. Extra handling to keep one mean per cluster

Parameters:

individual_variable_nameVariableName: Name of the individual latent variable for which this is the prior mean.
shapetuple of int: The shape of the model parameter (typically matching the variable’s dimensionality).

Returns:

ModelParameter: A new instance of ModelParameter configured as a prior mean.

Parameters:

ind_var_name (VariableName)
shape (Tuple[int, Ellipsis])

classmethod for_ind_std(ind_var_name, shape, **tol_kw)[source]¶

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

Parameters:

ind_var_nameVariableName: Name of the individual latent variable for which this is the prior std-dev.
shapetuple of int: The shape of the model parameter (typically matching the variable’s dimensionality).

Returns:

ModelParameter: A new instance of ModelParameter configured as a prior std-dev.

Parameters:

ind_var_name (VariableName)
shape (Tuple[int, Ellipsis])

classmethod for_ind_std_mixture(ind_var_name, shape, **tol_kw)[source]¶

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

Parameters:

ind_var_nameVariableName: Name of the individual latent variable for which this is the prior std-dev.
shapetuple of int: The shape of the model parameter (typically matching the variable’s dimensionality).

Returns:

ModelParameter: A new instance of ModelParameter configured as a prior std.

Parameters:

ind_var_name (VariableName)
shape (Tuple[int, Ellipsis])

classmethod for_probs(shape)[source]¶

Smart automatic definition of ModelParameter when it is the probabilities of a Gaussian mixture.

Parameters:

shapetuple of int: The shape of the model parameter (typically matching the variable’s dimensionality).

Returns:

ModelParameter: A new instance of ModelParameter configured as a probability vector.

Parameters:

shape (Tuple[int, Ellipsis])

class DataVariable[source]¶

Bases: IndepVariable

Variables for input data, that may be reset.

Attributes:

fixed_shapebool: Indicates whether the shape of the variable is fixed. For DataVariable. False by design, allowing for more flexible data injection.
is_settablebool: Flag indicating whether this variable can be set/reset directly in the state. True by desdign, meaning it can be modified externally.

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[source]¶

Bases: str, enum.Enum

Type of initialization for latent variables.

PRIOR_MODE = 'mode'¶

PRIOR_MEAN = 'mean'¶

PRIOR_SAMPLES = 'samples'¶

class LatentVariable[source]¶

Bases: IndepVariable

Unobserved variable that will be sampled, with symbolic prior distribution.

Attributes:

priorSymbolicDistribution: The symbolic prior distribution for the latent variable (e.g. Normal(‘xi_mean’, ‘xi_std’)).
sampling_kwsdict, optional: Optional keyword arguments to customize the sampling process (e.g. number of samples, random seed).

prior: SymbolicDistribution¶

sampling_kws: 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)[source]¶

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

Parameters:

named_varsMapping [VariableName, VariableInterface]: A mapping from variable names to their corresponding variable interfaces. These should include the parameters of the prior distribution.

Returns:

tuple of int: The shape of the prior distribution (without any replication for individual variables).

Raises:

LeaspyModelInputError: If any of the prior distribution’s parameter variables do not have a fixed shape.

Parameters:

named_vars (Mapping[VariableName, VariableInterface])

Return type:

tuple[int, Ellipsis]

abstractmethod get_regularity_variables(value_name)[source]¶

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

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

class PopulationLatentVariable[source]¶

Bases: LatentVariable

Population latent variable.

Attributes:

fixed_shapeClassVar`[:obj:`bool]: Indicates that the shape is fixed (True).

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)[source]¶

Return a function that may be used for initialization.

Parameters:

methodLatentVariableInitType or str: The method to be used.

Returns:

Tensor]: The initialization function.

Parameters:

method (Union[str, LatentVariableInitType])

Return type:

NamedInputFunction[Tensor]

get_regularity_variables(variable_name)[source]¶

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[source]¶

Bases: LatentVariable

Individual latent variable.

Attributes:

fixed_shapeClassVar`[:obj:`bool]: Indicates that the shape is fixed (True).

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)[source]¶

Return a function 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:

Tensor]: The initialization function.

Parameters:

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

Return type:

NamedInputFunction[Tensor]

get_regularity_variables(variable_name)[source]¶

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[source]¶

Bases: VariableInterface

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

Parameters:

fCallable`[..., :class:`~leaspy.variables.specs.VariableValue]: A deterministic function that computes this variable’s value from its input variables. The function should accept keyword arguments matching the variable names in parameters.

Attributes:

parametersfrozenset`[:class:`~leaspy.variables.specs.VariableName]: The set of variable names on which this linked variable depends. This is inferred internally from the function f.
is_settableClassVar`[:obj:`bool]: Indicates that this variable is not settable directly (False).
fixed_shapeClassVar`[obj:`bool]: Indicates whether the shape of the linked variable is fixed. By design it is False.

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()[source]¶

Return the set of variable names that this linked variable depends on.

Returns:

frozenset`[:class:`~leaspy.variables.specs.VariableName]: The names of ancestor variables used as inputs by this linked variable.

Return type:

frozenset[VariableName]

compute(state)[source]¶

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)[source]¶

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')¶