leaspy.variables.specs ====================== .. py:module:: leaspy.variables.specs Attributes ---------- .. autoapisummary:: leaspy.variables.specs.VariableName leaspy.variables.specs.VariableValue leaspy.variables.specs.VariableNameToValueMapping leaspy.variables.specs.VariablesToFrozenSet leaspy.variables.specs.VariablesLazyValuesRO leaspy.variables.specs.VariablesLazyValuesRW leaspy.variables.specs.SuffStatsRO leaspy.variables.specs.SuffStatsRW Classes ------- .. autoapisummary:: leaspy.variables.specs.VariableInterface leaspy.variables.specs.IndepVariable leaspy.variables.specs.Hyperparameter leaspy.variables.specs.Collect leaspy.variables.specs.ModelParameter leaspy.variables.specs.DataVariable leaspy.variables.specs.LatentVariableInitType leaspy.variables.specs.LatentVariable leaspy.variables.specs.PopulationLatentVariable leaspy.variables.specs.IndividualLatentVariable leaspy.variables.specs.LinkedVariable leaspy.variables.specs.NamedVariables Module Contents --------------- .. py:data:: VariableName .. py:data:: VariableValue .. py:data:: VariableNameToValueMapping .. py:data:: VariablesToFrozenSet .. py:data:: VariablesLazyValuesRO .. py:data:: VariablesLazyValuesRW .. py:data:: SuffStatsRO .. py:data:: SuffStatsRW .. py:class:: VariableInterface Interface for variable specifications. .. !! processed by numpydoc !! .. py:attribute:: is_settable :type: ClassVar[bool] Is True if and only if state of variables is intended to be manually modified by user. .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar[bool] Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data. .. !! processed by numpydoc !! .. py:method:: compute(state) :abstractmethod: Compute variable value from a `state` exposing a dict-like interface: var_name -> values. If not relevant for variable type return None. :Parameters: **state** : :class:`~leaspy.variables.specs.VariableNameToValueMapping` The state to use in order to perform computations. :Returns: :class:`~leaspy.variables.specs.VariableValue` The variable value computed from the state. .. !! processed by numpydoc !! .. py:method:: get_ancestors_names() :abstractmethod: Get the names of the variables that the current variable directly depends on. :Returns: :obj:`frozenset` [ :class:`~leaspy.variables.specs.VariableName`] The set of ancestors variable names. .. !! processed by numpydoc !! .. py:class:: IndepVariable Bases: :py:obj:`VariableInterface` Base class for variable that is not dependent on any other variable. .. !! processed by numpydoc !! .. py:method:: get_ancestors_names() Get the names of the variables that the current variable directly depends on. :Returns: :obj:`frozenset` [ :class:`~leaspy.variables.specs.VariableName`] The set of ancestors variable names. .. !! processed by numpydoc !! .. py:method:: 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: **state** : :class:`~leaspy.variables.specs.VariableNameToValueMapping` The state to use in order to perform computations. :Returns: :class:`~leaspy.variables.specs.VariableValue` or None: The variable value computed from the state. .. !! processed by numpydoc !! .. py:class:: Hyperparameter Bases: :py:obj:`IndepVariable` Hyperparameters that can not be reset. .. !! processed by numpydoc !! .. py:attribute:: value :type: VariableValue The hyperparameter value. .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar :value: True Whether the variable has a fixed shape or not. For hyperparameters this is True. .. !! processed by numpydoc !! .. py:attribute:: is_settable :type: ClassVar :value: False Whether the variable is mutable or not. For hyperparameters this is False. .. !! processed by numpydoc !! .. py:method:: to_device(device) Move the value to specified device (other variables never hold values so need for this method). :Parameters: **device** : :class:`torch.device` The device on which to move the variable value. .. !! processed by numpydoc !! .. py:property:: shape :type: tuple[int, Ellipsis] .. py: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** : :obj:`tuple` of :class:`~leaspy.variables.specs.VariableName`, optional Names of existing variables that should be included when collecting statistics. **dedicated_variables** : :obj:`dict` [:class:`~leaspy.variables.specs.VariableName`, :class:`~leaspy.variables.specs.LinkedVariable`], optional Custom or derived variables that will be included in the collection process. .. !! processed by numpydoc !! .. py:attribute:: existing_variables :type: tuple[VariableName, Ellipsis] :value: () .. py:attribute:: dedicated_variables :type: Optional[Mapping[VariableName, LinkedVariable]] :value: None .. py:property:: variables :type: tuple[VariableName, Ellipsis] Get the combined list of all variable names to be collected. :Returns: :obj:`tuple` of :class:`~leaspy.variables.specs.VariableName` Tuple containing both existing and dedicated variable names. .. !! processed by numpydoc !! .. py:class:: ModelParameter Bases: :py:obj:`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: **shape** : :obj:`tuple` of :obj:`int` Shape of the parameter tensor. It must be fixed and known in advance. **suff_stats** : :class:`~leaspy.variables.specs.Collect` A callable object that collects sufficient statistics required to compute the update. **update_rule** : :obj:`.typing.Callable` [..., :class:`~leaspy.variables.specs.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_in** : :obj:`.typing.Callable` [..., :class:`~leaspy.variables.specs.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_parameters** : :obj:`frozenset` of :class:`~leaspy.variables.specs.VariableName` Internal cache of variable names required by `update_rule`. **_update_rule_burn_in_parameters** : :obj:`frozenset` of :class:`~leaspy.variables.specs.VariableName` or None Internal cache of variable names required by `update_rule_burn_in`, if defined. **fixed_shape** : :obj:`bool` (class attribute) Indicates that this variable has a fixed shape (True by design). **is_settable** : :obj:`bool` (class attribute) Flags this variable as being settable externally (True by design). .. !! processed by numpydoc !! .. py:attribute:: shape :type: tuple[int, Ellipsis] .. py:attribute:: suff_stats :type: 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) .. !! processed by numpydoc !! .. py:attribute:: update_rule :type: Callable[Ellipsis, VariableValue] Update rule for normal phase, and memory-less (burn-in) phase unless `update_rule_burn_in` is not None. .. !! processed by numpydoc !! .. py:attribute:: update_rule_burn_in :type: Optional[Callable[Ellipsis, VariableValue]] :value: None Specific rule for burn-in (currently implemented for some variables -> e.g. `xi_std`) .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar :value: True Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data. .. !! processed by numpydoc !! .. py:attribute:: is_settable :type: ClassVar :value: True Is True if and only if state of variables is intended to be manually modified by user. .. !! processed by numpydoc !! .. py:method:: compute_update(*, state, suff_stats, burn_in) Compute the updated value for the model parameter using a maximization step. :Parameters: **state** : :class:`~leaspy.variables.specs.VariableNameToValueMapping` The state to use for computations. **suff_stats** : :class:`~leaspy.variables.specs.SuffStatsRO` The sufficient statistics to use. **burn_in** : :obj:`bool` If True, use the update rule in burning phase. :Returns: :class:`~leaspy.variables.specs.VariableValue` The computed variable value. .. !! processed by numpydoc !! .. py:method:: for_pop_mean(population_variable_name, shape) :classmethod: Smart automatic definition of `ModelParameter` when it is the mean of Gaussian prior of a population latent variable. :Parameters: **population_variable_name** : :class:`~leaspy.variables.specs.VariableName` Name of the population latent variable for which this is the prior mean. **shape** : :obj:`tuple` of :obj:`int` The shape of the model parameter (typically matching the variable's dimensionality). :Returns: :class:`~leaspy.variables.specs.ModelParameter` A new instance of `ModelParameter` configured as a prior mean. .. !! processed by numpydoc !! .. py:method:: for_ind_mean(individual_variable_name, shape) :classmethod: Smart automatic definition of `ModelParameter` when it is the mean of Gaussian prior of an individual latent variable. :Parameters: **individual_variable_name** : :class:`~leaspy.variables.specs.VariableName` Name of the individual latent variable for which this is the prior mean. **shape** : :obj:`tuple` of :obj:`int` The shape of the model parameter (typically matching the variable's dimensionality). :Returns: :class:`~leaspy.variables.specs.ModelParameter` A new instance of `ModelParameter` configured as a prior mean. .. !! processed by numpydoc !! .. py:method:: for_ind_mean_mixture(ind_var_name, shape) :classmethod: 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_name** : :class:`~leaspy.variables.specs.VariableName` Name of the individual latent variable for which this is the prior mean. **shape** : :obj:`tuple` of :obj:`int` The shape of the model parameter (typically matching the variable's dimensionality). :Returns: :class:`~leaspy.variables.specs.ModelParameter` A new instance of `ModelParameter` configured as a prior mean. .. !! processed by numpydoc !! .. py:method:: for_ind_std(ind_var_name, shape, **tol_kw) :classmethod: Smart automatic definition of `ModelParameter` when it is the std-dev of Gaussian prior of an individual latent variable. :Parameters: **ind_var_name** : :class:`~leaspy.variables.specs.VariableName` Name of the individual latent variable for which this is the prior std-dev. **shape** : :obj:`tuple` of :obj:`int` The shape of the model parameter (typically matching the variable's dimensionality). :Returns: :class:`~leaspy.variables.specs.ModelParameter` A new instance of `ModelParameter` configured as a prior std-dev. .. !! processed by numpydoc !! .. py:method:: for_ind_std_mixture(ind_var_name, shape, **tol_kw) :classmethod: Smart automatic definition of `ModelParameter` when it is the std-dev of Gaussian prior of an individual latent variable. :Parameters: **ind_var_name** : :class:`~leaspy.variables.specs.VariableName` Name of the individual latent variable for which this is the prior std-dev. **shape** : :obj:`tuple` of :obj:`int` The shape of the model parameter (typically matching the variable's dimensionality). :Returns: :class:`~leaspy.variables.specs.ModelParameter` A new instance of `ModelParameter` configured as a prior std. .. !! processed by numpydoc !! .. py:method:: for_probs(shape) :classmethod: Smart automatic definition of `ModelParameter` when it is the probabilities of a Gaussian mixture. :Parameters: **shape** : :obj:`tuple` of :obj:`int` The shape of the model parameter (typically matching the variable's dimensionality). :Returns: :class:`~leaspy.variables.specs.ModelParameter` A new instance of `ModelParameter` configured as a probability vector. .. !! processed by numpydoc !! .. py:class:: DataVariable Bases: :py:obj:`IndepVariable` Variables for input data, that may be reset. :Attributes: **fixed_shape** : :obj:`bool` Indicates whether the shape of the variable is fixed. For `DataVariable`. `False` by design, allowing for more flexible data injection. **is_settable** : :obj:`bool` Flag indicating whether this variable can be set/reset directly in the state. `True` by desdign, meaning it can be modified externally. .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar :value: False Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data. .. !! processed by numpydoc !! .. py:attribute:: is_settable :type: ClassVar :value: True Is True if and only if state of variables is intended to be manually modified by user. .. !! processed by numpydoc !! .. py:class:: LatentVariableInitType Bases: :py:obj:`str`, :py:obj:`enum.Enum` Type of initialization for latent variables. .. !! processed by numpydoc !! .. py:attribute:: PRIOR_MODE :value: 'mode' .. py:attribute:: PRIOR_MEAN :value: 'mean' .. py:attribute:: PRIOR_SAMPLES :value: 'samples' .. py:class:: LatentVariable Bases: :py:obj:`IndepVariable` Unobserved variable that will be sampled, with symbolic prior distribution. :Attributes: **prior** : :class:`~leaspy.variables.distributions.SymbolicDistribution` The symbolic prior distribution for the latent variable (e.g. `Normal('xi_mean', 'xi_std')`). **sampling_kws** : :obj:`dict`, optional Optional keyword arguments to customize the sampling process (e.g. number of samples, random seed). .. !! processed by numpydoc !! .. py:attribute:: prior :type: leaspy.variables.distributions.SymbolicDistribution .. py:attribute:: sampling_kws :type: Optional[leaspy.utils.typing.KwargsType] :value: None .. py:attribute:: is_settable :type: ClassVar :value: True Is True if and only if state of variables is intended to be manually modified by user. .. !! processed by numpydoc !! .. py:method:: get_prior_shape(named_vars) Get shape of prior distribution (i.e. without any expansion for `IndividualLatentVariable`). :Parameters: **named_vars** : :obj:`Mapping` [:class:`~leaspy.variables.specs.VariableName`, :class:`~leaspy.variables.specs.VariableInterface`] A mapping from variable names to their corresponding variable interfaces. These should include the parameters of the prior distribution. :Returns: :obj:`tuple` of :obj:`int` The shape of the prior distribution (without any replication for individual variables). :Raises: :exc:`LeaspyModelInputError` If any of the prior distribution’s parameter variables do not have a fixed shape. .. !! processed by numpydoc !! .. py:method:: get_regularity_variables(value_name) :abstractmethod: Get extra linked variables to compute regularity term for this latent variable. .. !! processed by numpydoc !! .. py:class:: PopulationLatentVariable Bases: :py:obj:`LatentVariable` Population latent variable. :Attributes: **fixed_shape** : `ClassVar`[:obj:`bool`] Indicates that the shape is fixed (True). .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar :value: True Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data. .. !! processed by numpydoc !! .. py:method:: get_init_func(method) Return a function that may be used for initialization. :Parameters: **method** : :class:`~leaspy.variables.specs.LatentVariableInitType` or :obj:`str` The method to be used. :Returns: :class:`~leaspy.utils.functional._named_imput_function.NamedInputFunction`[:class:`torch.Tensor`] The initialization function. .. !! processed by numpydoc !! .. py:method:: get_regularity_variables(variable_name) Return the negative log likelihood regularity for the provided variable name. :Parameters: **variable_name** : :class:`~leaspy.variables.specs.VariableName` The name of the variable for which to retrieve regularity. :Returns: :obj:`dict` [ :class:`~leaspy.variables.specs.VariableName`, :class:`~leaspy.variables.specs.LinkedVariable`] The dictionary holding the :class:`~leaspy.variables.specs.LinkedVariable` for the regularity. .. !! processed by numpydoc !! .. py:class:: IndividualLatentVariable Bases: :py:obj:`LatentVariable` Individual latent variable. :Attributes: **fixed_shape** : `ClassVar`[:obj:`bool`] Indicates that the shape is fixed (True). .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar :value: False Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data. .. !! processed by numpydoc !! .. py:method:: get_init_func(method, *, n_individuals) Return a function that may be used for initialization. :Parameters: **method** : :class:`~leaspy.variables.specs.LatentVariableInitType` or :obj:`str` The method to be used. **n_individuals** : :obj:`int` The number of individuals, used to define the shape. :Returns: :class:`~leaspy.utils.functional._named_imput_function.NamedInputFunction`[:class:`torch.Tensor`] The initialization function. .. !! processed by numpydoc !! .. py:method:: get_regularity_variables(variable_name) Return the negative log likelihood regularity for the provided variable name. :Parameters: **variable_name** : :class:`~leaspy.variables.specs.VariableName` The name of the variable for which to retrieve regularity. :Returns: :obj:`dict` [ :class:`~leaspy.variables.specs.VariableName`, :class:`~leaspy.variables.specs.LinkedVariable`] The dictionary holding the :class:`~leaspy.variables.specs.LinkedVariable` for the regularity. .. !! processed by numpydoc !! .. py:class:: LinkedVariable Bases: :py:obj:`VariableInterface` Variable which is a deterministic expression of other variables (we directly use variables names instead of mappings: kws <-> vars). :Parameters: **f** : :obj:`Callable`[..., :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: **parameters** : :obj:`frozenset`[: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_settable** : `ClassVar`[:obj:`bool`] Indicates that this variable is not settable directly (`False`). **fixed_shape** : `ClassVar`[obj:`bool`] Indicates whether the shape of the linked variable is fixed. By design it is `False`. .. !! processed by numpydoc !! .. py:attribute:: f :type: Callable[Ellipsis, VariableValue] .. py:attribute:: parameters :type: frozenset[VariableName] .. py:attribute:: is_settable :type: ClassVar :value: False Is True if and only if state of variables is intended to be manually modified by user. .. !! processed by numpydoc !! .. py:attribute:: fixed_shape :type: ClassVar :value: False Is True as soon as we guarantee that shape of variable is only dependent on model hyperparameters, not data. .. !! processed by numpydoc !! .. py:method:: get_ancestors_names() Return the set of variable names that this linked variable depends on. :Returns: :obj:`frozenset`[:class:`~leaspy.variables.specs.VariableName`] The names of ancestor variables used as inputs by this linked variable. .. !! processed by numpydoc !! .. py:method:: compute(state) Compute the variable value from a given State. :Parameters: **state** : :class:`~leaspy.variables.specs.VariableNameToValueMapping` The state to use for computations. :Returns: :class:`~leaspy.variables.specs.VariableValue` The value of the variable. .. !! processed by numpydoc !! .. py:class:: NamedVariables(*args, **kws) Bases: :py:obj:`collections.UserDict` Convenient dictionary for named variables specifications. In particular, it: 1. forbids the collisions in variable names when assigning/updating the collection 2. forbids the usage of some reserved names like 'state' or 'suff_stats' 3. automatically adds implicit variables when variables of certain kind are added (e.g. dedicated vars for sufficient stats of ModelParameter) 4. 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. .. !! processed by numpydoc !! .. py:attribute:: FORBIDDEN_NAMES :type: ClassVar .. py:attribute:: AUTOMATIC_VARS :type: ClassVar :value: ('nll_regul_ind_sum_ind', 'nll_regul_ind_sum')