leaspy.models.mixture ===================== .. py:module:: leaspy.models.mixture Classes ------- .. autoapisummary:: leaspy.models.mixture.TimeReparametrizedMixtureModel leaspy.models.mixture.RiemanianManifoldMixtureModel leaspy.models.mixture.LogisticMixtureInitializationMixin leaspy.models.mixture.LogisticMultivariateMixtureModel Module Contents --------------- .. py:class:: TimeReparametrizedMixtureModel(name, **kwargs) Bases: :py:obj:`leaspy.models.mcmc_saem_compatible.McmcSaemCompatibleModel` A time-reparametrized model tailored to handle mixture models with multiple clusters. This class extends `TimeReparametrizedModel` to incorporate mixture-specific behaviors, including support for multiple clusters (`n_clusters`) and corresponding vectorized parameters. :Parameters: **name** : :obj:`str` Name of the model. **source_dimension** : Optional[:obj:`int`] Number of sources. Dimension of spatial components (default is None). **\*\*kwargs: :obj:`dict`** Additional hyperparameters for the model. Must include: - 'n_clusters': int Number of mixture components (must be ≥ 2). - 'dimension' or 'features': int or list Dimensionality of the input data. - 'obs_models': str, list, or dict (optional) Specification of the observation model(s). Defaults to "gaussian-diagonal". :Raises: :exc:`.LeaspyModelInputError` If inconsistent hyperparameters. .. !! processed by numpydoc !! .. py:property:: xi_mean :type: torch.Tensor Return the mean of xi as a tensor. .. !! processed by numpydoc !! .. py:property:: xi_std :type: torch.Tensor Return the standard deviation of xi as a tensor. .. !! processed by numpydoc !! .. py:property:: tau_std :type: torch.Tensor Return the standard deviation of tau as a tensor. .. !! processed by numpydoc !! .. py:property:: noise_std :type: torch.Tensor Return the standard deviation of the model as a tensor. .. !! processed by numpydoc !! .. py:property:: sources_mean :type: torch.Tensor Return the mean of the sources as a tensor. .. !! processed by numpydoc !! .. py:property:: sources_std :type: torch.Tensor Return the standard deviation of the sources as a tensor. .. !! processed by numpydoc !! .. py:attribute:: source_dimension :type: Optional[int] :value: None .. py:method:: get_variables_specs() Return the specifications of the variables (latent variables, derived variables, model 'parameters') that are part of the model. :Returns: :class:`~leaspy.variables.specs.NamedVariables` A dictionary-like object containing specifications for the variables .. !! processed by numpydoc !! .. py:property:: has_sources :type: bool Indicates whether the model includes sources. :Returns: :obj:`bool` True if `source_dimension` is a positive integer. False otherwise. .. !! processed by numpydoc !! .. py:method:: time_reparametrization(*, t, alpha, tau) :staticmethod: Tensorized time reparametrization formula. .. warning:: Shapes of tensors must be compatible between them. :Parameters: **t** : :class:`torch.Tensor` Timepoints to reparametrize **alpha** : :class:`torch.Tensor` Acceleration factors of individual(s) **tau** : :class:`torch.Tensor` Time-shift(s) of individual(s) :Returns: :class:`torch.Tensor` Reparametrized time of same shape as `timepoints` .. !! processed by numpydoc !! .. py:method:: put_individual_parameters(state, dataset) Initialize individual latent parameters in the given state if not already set. :Parameters: **state** : :class:`~leaspy.variables.state.State` The current state object that holds all the variables **dataset** : :class:`~leaspy.io.data.Data.Dataset` Dataset used to initialize latent variables accordingly. .. !! processed by numpydoc !! .. py:method:: to_dict(*, with_mixing_matrix = True) Export model object as dictionary ready for :term:`JSON` saving. :Parameters: **with_mixing_matrix** : :obj:`bool` (default ``True``) Save the :term:`mixing matrix` in the exported file in its 'parameters' section. .. warning:: It is not a real parameter and its value will be overwritten at model loading (orthonormal basis is recomputed from other "true" parameters and mixing matrix is then deduced from this orthonormal basis and the betas)! It was integrated historically because it is used for convenience in browser webtool and only there... :Returns: :class:`~leaspy.utils.typing.KwargsType` The object as a dictionary. .. !! processed by numpydoc !! .. py:class:: RiemanianManifoldMixtureModel(name, variables_to_track = None, **kwargs) Bases: :py:obj:`TimeReparametrizedMixtureModel` A riemannian manifold model tailored to handle mixture models with multiple clusters. This class extends `RiemanianManifoldModel` to incorporate mixture-specific behaviors, mainly the handling of sources for multiple clusters. :Parameters: **name** : :obj:`str` The name of the model. **\*\*kwargs** Hyperparameters of the model (including `noise_model`) :Raises: :exc:`.LeaspyModelInputError` * If hyperparameters are inconsistent .. !! processed by numpydoc !! .. py:attribute:: tracked_variables .. py:attribute:: tracked_variables_ordered :value: ['g', 'v0', 'noise_std', 'tau_mean', 'tau_std', 'xi_mean', 'xi_std', 'nll_attach',... .. py:method:: compute_sufficient_statistics(state) :classmethod: Compute the model's :term:`sufficient statistics`. :Parameters: **state** : :class:`~leaspy.variables.state.State` The state to pick values from. :Returns: SuffStatsRW The computed sufficient statistics. .. !! processed by numpydoc !! .. py:method:: get_variables_specs() Return the specifications of the variables (latent variables, derived variables, model 'parameters') that are part of the model. :Returns: :class:`~leaspy.variables.specs.NamedVariables` A dictionary-like object mapping variable names to their specifications. These include `ModelParameter`, `Hyperparameter`, `PopulationLatentVariable`, and `LinkedVariable` instances. .. !! processed by numpydoc !! .. py:method:: metric(*, g) :staticmethod: :abstractmethod: .. py:method:: model_no_sources(*, rt, metric, v0, g) :classmethod: Return the model output when sources(spatial components) are not present. :Parameters: **rt** : :class:`torch.Tensor` The reparametrized time. **metric** : Any The metric tensor used for computing the spatial/temporal influence. **v0** : Any The values of the population parameter `v0` for each feature. **g** : Any The values of the population parameter `g` for each feature. :Returns: :class:`torch.Tensor` The model output without contribution from source shifts. .. rubric:: Notes This implementation delegates to `model_with_sources` with `space_shifts` set to a zero tensor of shape (1, 1), effectively removing source effects. .. !! processed by numpydoc !! .. py:method:: model_with_sources(*, rt, space_shifts, metric, v0, g) :classmethod: :abstractmethod: .. py:class:: LogisticMixtureInitializationMixin .. py:class:: LogisticMultivariateMixtureModel(name, **kwargs) Bases: :py:obj:`LogisticMixtureInitializationMixin`, :py:obj:`RiemanianManifoldMixtureModel` Mixture Manifold model for multiple variables of interest (logistic formulation). .. !! processed by numpydoc !! .. py:method:: get_variables_specs() Return the specifications of the variables (latent variables, derived variables, model 'parameters') that are part of the model. :Returns: :class:`~leaspy.variables.specs.NamedVariables` A dictionary-like object mapping variable names to their specifications. These include `ModelParameter`, `Hyperparameter`, `PopulationLatentVariable`, and `LinkedVariable` instances. .. !! processed by numpydoc !! .. py:method:: metric(*, g) :staticmethod: Compute the metric tensor from input tensor `g`. This function calculates the metric as \((g + 1)^2 / g\) element-wise. :Parameters: **g** : t :class:`torch.Tensor` Input tensor with values of the population parameter `g` for each feature. :Returns: :class:`torch.Tensor` The computed metric tensor, same shape as g(number of features) .. !! processed by numpydoc !! .. py:method:: model_with_sources(*, rt, space_shifts, metric, v0, g) :classmethod: Return the model output when sources(spatial components) are present. :Parameters: **rt** : :class:`~leaspy.uitls.weighted_tensor._weighted_tensor.TensorOrWeightedTensor`[:obj:`float`] Tensor containing the reparametrized time. **space_shifts** : `~leaspy.uitls.weighted_tensor._weighted_tensor.TensorOrWeightedTensor`[:obj:`float`] Tensor containing the values of the space-shifts **metric :`~leaspy.uitls.weighted_tensor._weighted_tensor.TensorOrWeightedTensor`[:obj:`float`]** Tensor containing the metric tensor used for computing the spatial/temporal influence. **v0** : `~leaspy.uitls.weighted_tensor._weighted_tensor.TensorOrWeightedTensor`[:obj:`float`] Tensor containing the values of the population parameter `v0` for each feature. **g** : `~leaspy.uitls.weighted_tensor._weighted_tensor.TensorOrWeightedTensor`[:obj:`float`] Tensor containing the values of the population parameter `g` for each feature. :Returns: :class:`torch.Tensor` Weighted value tensor after applying sigmoid transformation, representing the model output with sources. .. !! processed by numpydoc !!