leaspy.variables.state

This module defines the State of stateful models.

A state contains 2 main components: 1. The relationships between the variables through a VariablesDAG 2. The values of each variable of the DAG as a mapping between variable names and their values

The State class is crucial for stateful models with its logic for efficiently retrieving variable values. This class relies on a caching mechanism that enables quick queries.

Classes

`StateForkType`	The strategy used to cache forked values in `State`.
`State`	Dictionary of cached values corresponding to the stateless DAG instance.

Module Contents

class StateForkType(*args, **kwds)

Bases: enum.Enum

The strategy used to cache forked values in State.

REF : caching using references COPY : caching using deepcopy

Notes

If using REF beware that values will NOT be copied (it only keeps references of values), so do NOT mutate them directly or the behavior will be unexpected.

REF

COPY

to_cache(d)

Get the values to cache, depending on forking type.

Parameters:: d (leaspy.variables.specs.VariablesLazyValuesRW)
Return type:: leaspy.variables.specs.VariablesLazyValuesRO

class State(dag, *, auto_fork_type=None)

Bases: collections.abc.MutableMapping

Dictionary of cached values corresponding to the stateless DAG instance.

Parameters:

dagVariablesDAG: The stateless DAG which state will hold values for.
auto_fork_typeStateForkType or None (default): Refer to StateForkType class and auto_fork_type

Attributes:

dagVariablesDAG: The stateless DAG which the state instance will hold values for.
auto_fork_typeStateForkType or None: If not StateForkType.NONE each dictionary assignment will lead to the partial caching of previous value and all its children, so they can be reverted without computation. The exact caching strategy depends on flag (caching by reference or by copy) Can be manually set or via auto_fork context manager.
_valuesMutableMapping[VarName, Optional[VarValue]]: Private cache for values (computations are lazy thus some values may be None). All not None values are always self-consistent with respect to DAG dependencies.
_last_forkNone or Mapping[VarName, Optional[VarValue]]: If not None, holds the previous partial state values so they may be .revert(). Automatically populated on assignment operations as soon as auto_fork_type is not NONE. Example: if you set a new value for a, then value of a and of all its children just before assignment are held until either reversion or a new assignment.

Parameters:

dag (VariablesDAG)
auto_fork_type (Optional[StateForkType])

dag

auto_fork_type = None

property tracked_variables: set[leaspy.variables.specs.VariableName, Ellipsis]

Returns a set of names for the variables that are tracked by the State.

Return type:: set[leaspy.variables.specs.VariableName, Ellipsis]

track_variables(variable_names)

Add some variables to the tracked variables.

Parameters:

variable_namesIterable of VariableName: The names of the variables to be added to the tracked variables.

Parameters:

variable_names (Iterable[leaspy.variables.specs.VariableName])

Return type:

None

track_variable(variable_name)

Add a single variable to the tracked variables.

Parameters:

variable_nameVariableName: The name of the variable to be added to the tracked variables.

Parameters:

variable_name (leaspy.variables.specs.VariableName)

Return type:

None

untrack_variables(variable_names)

Remove some variables from the tracked variables.

Parameters:

variable_namesIterable of VariableName: The names of the variables to be removed from the tracked variables.

Parameters:

variable_names (Iterable[leaspy.variables.specs.VariableName])

Return type:

None

untrack_variable(variable_name)

Remove a single variable from the tracked variables.

Parameters:

variable_nameVariableName: The name of the variable to be removed from the tracked variables.

Parameters:

variable_name (leaspy.variables.specs.VariableName)

Return type:

None

clear()

Reset last forked state and reset all values to their canonical values.

Return type:: None

clone(*, disable_auto_fork=False, keep_last_fork=False)

Clone current state without copying the DAG.

Parameters:

disable_auto_forkbool, optional: Whether to allow auto-fork or not. Default=False.
keep_last_forkbool, optional: Whether to keep the last fork or not. Default=False.

Returns:

State: The new cloned state instance.

Parameters:

disable_auto_fork (bool)
keep_last_fork (bool)

Return type:

State

auto_fork(type=StateForkType.REF)

Provide a context manager interface with temporary auto_fork_type set to type.

Parameters:: type (Optional[StateForkType])

is_variable_set(name)

Returns True if the variable is in the DAG and if its value is not None.

Parameters:: name (leaspy.variables.specs.VariableName)
Return type:: bool

are_variables_set(variable_names)

Returns True if all the variables are in the DAG with values different from None.

Parameters:: variable_names (Iterable[leaspy.variables.specs.VariableName])
Return type:: bool

put(variable_name, variable_value, *, indices=(), accumulate=False)

Smart and protected assignment of a variable value, but potentially on a subset of indices, adding (accumulating) values and OUT-OF-PLACE.

Parameters:

variable_nameVariableName: The name of the variable.
variable_valueVariableValue: The new value to put in the variable name.
indicestuple of int, optional: If set, the operation will happen on a subset of indices. Default=()
accumulatebool, optional: If set to True, the new variable value will be added to the old value. Otherwise, it will be assigned. Default=False

Parameters:

variable_name (leaspy.variables.specs.VariableName)
variable_value (leaspy.variables.specs.VariableValue)
indices (tuple[int, Ellipsis])
accumulate (bool)

Return type:

None

precompute_all()

Pre-compute all values of the graph (assuming leaves already have valid values).

Return type:: None

revert(subset=None, *, right_broadcasting=True)

Revert state to previous forked state. Forked state is then reset.

Parameters:

subsetVariableValue or None: If not None, the reversion is only partial: * subset = True <=> revert previous state for those indices * subset = False <=> keep current state for those indices <!> User is responsible for having tensor values that are consistent with subset shape (i.e. valid broadcasting) for the forked node and all of its children.

<!> When the current OR forked state is not set (value = None) on a particular node of forked DAG, then the reverted result is always None.
right_broadcastingbool, optional: If True and if subset is not None, then the subset of indices to revert uses right-broadcasting, instead of the standard left-broadcasting. Default=True.

Parameters:

subset (Optional[leaspy.variables.specs.VariableValue])
right_broadcasting (bool)

Return type:

None

to_device(device)

Move values to the specified device (in-place).

Parameters:

devicetorch.device

Parameters:

device (device)

Return type:

None

put_population_latent_variables(method)

Put some predefined values in state for all population latent variables (in-place).

Parameters:: method (Optional[Union[str, LatentVariableInitType]])
Return type:: None

put_individual_latent_variables(method=None, *, n_individuals=None, df=None)

Put some predefined values in state for all individual latent variables (in-place).

Parameters:

method (Optional[Union[str, LatentVariableInitType]])
n_individuals (Optional[int])
df (Optional[DataFrame])

Return type:

None

save(output_folder, iteration=None)

Save the tracked variable values of the state.

Parameters:

output_folderstr: The path to the output folder in which the state’s tracked variables should be saved.
iterationint, optional: The iteration number when this method is called from an algorithm. This iteration number will appear at the beginning of the row.

Parameters:

output_folder (str)
iteration (Optional[int])

Return type:

None

get_tensor_value(variable_name)

Return the value of the provided variable as a torch tensor.

Parameters:

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

Returns:

VariableValue: The value of the variable.

Parameters:

variable_name (leaspy.variables.specs.VariableName)

Return type:

leaspy.variables.specs.VariableValue

get_tensor_values(variable_names)

Return the values of the provided variables as torch tensors.

Parameters:

variable_namesIterable of VariableName: The names of the variables for which to retrieve the values.

Returns:

tuple of VariableValue: The values of the variables.

Parameters:

variable_names (Iterable[leaspy.variables.specs.VariableName])

Return type:

tuple[leaspy.variables.specs.VariableValue, Ellipsis]