leaspy.models.base ================== .. py:module:: leaspy.models.base Classes ------- .. autoapisummary:: leaspy.models.base.InitializationMethod leaspy.models.base.ModelInterface leaspy.models.base.BaseModel Module Contents --------------- .. py:class:: InitializationMethod Bases: :py:obj:`str`, :py:obj:`enum.Enum` Possible initialization methods for Leaspy models. :Attributes: **DEFAULT** : :obj:`str` Default initialization method. **RANDOM** : :obj:`str` Random initialization method. .. !! processed by numpydoc !! .. py:attribute:: DEFAULT :value: 'default' .. py:attribute:: RANDOM :value: 'random' .. py:class:: ModelInterface Bases: :py:obj:`abc.ABC` This is the public interface for Leaspy models. It defines the methods and properties that all models should implement. It is not meant to be instantiated directly, but rather to be inherited by concrete model classes. .. !! processed by numpydoc !! .. py:property:: name :type: str :abstractmethod: The name of the model. :Returns: :obj:`str` .. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:property:: is_initialized :type: bool :abstractmethod: True if the model is initialized, False otherwise. :Returns: :obj:`bool` .. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:property:: dimension :type: int :abstractmethod: Number of features. :Returns: :obj:`int` .. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:property:: features :type: list[leaspy.utils.typing.FeatureType] :abstractmethod: List of model features (`None` if not initialization). :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:property:: parameters :type: leaspy.utils.typing.DictParamsTorch :abstractmethod: Dictionary of values for model parameters. :Returns: :class:`~leaspy.utils.typing.DictParamsTorch` .. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:property:: hyperparameters :type: leaspy.utils.typing.DictParamsTorch :abstractmethod: Dictionary of values for model hyperparameters. :Returns: :class:`~leaspy.utils.typing.DictParamsTorch` .. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:method:: save(path, **kwargs) :abstractmethod: Save model as json model parameter file. :Parameters: **path** : :obj:`str` or :obj:`Path` The path to store the model's parameters. **\*\*kwargs** : :obj:`dict` Additional parameters for writing. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:method:: load(path_to_model_settings) :classmethod: :abstractmethod: Load a model from a json model parameter file. :Parameters: **path_to_model_settings** : :obj:`str` or :obj:`Path` The path to the model's parameters file. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:method:: fit(data = None, algorithm = None, algorithm_settings = None, algorithm_settings_path = None, **kwargs) :abstractmethod: Estimate the model's parameters :math:`\theta` for a given dataset and a given algorithm. These model's parameters correspond to the fixed-effects of the mixed-effects model. There are three ways to provide parameters to the fitting algorithm: 1. By providing an instance of :class:`~leaspy.algo.AlgorithmSettings` 2. By providing a path to a serialized :class:`~leaspy.algo.AlgorithmSettings` 3. By providing the algorithm name and parameters directly If settings are provided in multiple ways, the order above will prevail. :Parameters: **data** : :obj:`pd.DataFrame` or :class:`~leaspy.io.Data` or :class:`~leaspy.io.Dataset`, optional Contains the information of the individuals, in particular the time-points :math:`(t_{i,j})` and the observations :math:`(y_{i,j})`. **algorithm** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName`,optional The name of the algorithm to use. .. note:: Use this if you want to provide algorithm settings through kwargs. **algorithm_settings** : :class:`~leaspy.algo.AlgorithmSettings`, optional The algorithm settings to use. .. note:: Use this if you want to customize algorithm settings through the :class:`~leaspy.algo.AlgorithmSettings` class. If provided, the fit will rely on these settings. **algorithm_settings_path** : :obj:`str` or :obj:`Path`, optional The path to the algorithm settings file. .. note:: If provided, the settings from the file will be used instead of the settings provided through kwarsg. **\*\*kwargs** : :obj:`dict` Contains the algorithm's settings. :Raises: NotImplementedError .. .. rubric:: Examples Fit a logistic model on a longitudinal dataset, display the group parameters >>> from leaspy.models import LogisticModel >>> from leaspy.datasets import load_dataset >>> putamen_df = load_dataset("parkinson-putamen") >>> model = LogisticModel(name="test-model-logistic") >>> model.fit(putamen_df, "mcmc_saem", seed=0, print_periodicity=50) >>> print(model) === MODEL === betas_mean : [] log_g_mean : [-0.8394] log_v0_mean : [-3.7930] noise_std : 0.021183 tau_mean : [64.6920] tau_std : [10.0864] xi_std : [0.5232] .. !! processed by numpydoc !! .. py:method:: personalize(data = None, algorithm = None, algorithm_settings = None, algorithm_settings_path = None, **kwargs) :abstractmethod: Estimate individual parameters for each `ID` of a given dataset. These individual parameters correspond to the random-effects :math:`(z_{i,j})` of the mixed-effects model. :Parameters: **data** : :obj:`pd.DataFrame` or :class:`~leaspy.io.Data` or :class:`~leaspy.io.Dataset`, optional Contains the information of the individuals, in particular the time-points :math:`(t_{i,j})` and the observations :math:`(y_{i,j})`. **algorithm** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName`, optional The name of the algorithm to use. **algorithm_settings** : :class:`~leaspy.algo.AlgorithmSettings`, optional The algorithm settings to use. .. note:: Use this if you want to customize algorithm settings through the :class:`~leaspy.algo.AlgorithmSettings` class. If provided, the fit will rely on these settings. **algorithm_settings_path** : :obj:`str` or :obj:`Path`, optional The path to the algorithm settings file. .. note:: If provided, the settings from the file will be used instead of the settings provided. **\*\*kwargs** : :obj:`dict` Contains the algorithm's settings. :Returns: **ips** : :class:`~leaspy.io.IndividualParameters` Individual parameters computed. :Raises: NotImplementedError .. .. rubric:: Examples Compute the individual parameters for a given longitudinal dataset and calibrated model, then display the histogram of the log-acceleration: >>> from leaspy.datasets import load_model, load_dataset >>> model = load_model("parkinson-putamen") >>> putamen_df = load_dataset("parkinson-putamen") >>> individual_parameters = model.personalize(putamen_df, "scipy_minimize", seed=0) .. !! processed by numpydoc !! .. py:method:: estimate(timepoints, individual_parameters, *, to_dataframe = None) :abstractmethod: Return the model values for individuals characterized by their individual parameters :math:`z_i` at time-points :math:`(t_{i,j})_j`. :Parameters: **timepoints** : :obj:`pd.MultiIndex` or :obj:`dict` [:obj:`IDType`, :obj:`list` [:obj:`float` ] ] Contains, for each individual, the time-points to estimate. It can be a unique time-point or a list of time-points. **individual_parameters** : :class:`~leaspy.io.IndividualParameters` Corresponds to the individual parameters of individuals. **to_dataframe** : :obj:`bool`, optional Whether to output a dataframe of estimations? If None: default is to be True if and only if timepoints is a `pandas.MultiIndex` :Returns: **individual_trajectory** : :obj:`pd.MultiIndex` or :obj:`dict` [:obj:`IDType`, :obj:`list` [:obj:`float`]] Key: patient indices. Value: :class:`numpy.ndarray` of the estimated value, in the shape (number of timepoints, number of features) :Raises: NotImplementedError .. .. rubric:: Examples Given the individual parameters of two subjects, estimate the features of the first at 70, 74 and 80 years old and at 71 and 72 years old for the second. >>> from leaspy.datasets import load_model, load_individual_parameters, load_dataset >>> model = load_model("parkinson-putamen") >>> individual_parameters = load_individual_parameters("parkinson-putamen") >>> df_train = load_dataset("parkinson-putamen-train_and_test").xs("train", level="SPLIT") >>> timepoints = {'GS-001': (70, 74, 80), 'GS-002': (71, 72)} >>> estimations = model.estimate(timepoints, individual_parameters) .. !! processed by numpydoc !! .. py:method:: simulate(individual_parameters, data = None, **kwargs) :abstractmethod: Run the simulation pipeline using a leaspy model. This method simulates longitudinal data using the given leaspy model. It performs the following steps: - Retrieves individual parameters (IP) from fixed effects of the model. - Loads the specified Leaspy model. - Generates visit ages (timepoints) for each individual (based on specifications in visits_type). - Simulates observations at those visit ages. - Packages the result into a `Result` object, including simulated data, individual parameters, and the model's noise standard deviation. :Parameters: **individual_parameters** : :class:`~leaspy.io.IndividualParameters` Individual parameters to use for the simulation. **data** : :obj:`pd.DataFrame` or :class:`~leaspy.io.Data` or :class:`~leaspy.io.Dataset` Data object. If None, returns empty Result. **\*\*kwargs** : :obj:`dict` Additional arguments for algorithm settings. :Returns: **simulated_data** : :class:`~leaspy.io.outputs.result.Result` Contains the generated individual parameters & the corresponding generated scores. Returns empty Result if any required input is None. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:class:: BaseModel(name, **kwargs) Bases: :py:obj:`ModelInterface` Base model class from which all ``Leaspy`` models should inherit. It implements the :class:`~leaspy.models.ModelInterface`. .. !! processed by numpydoc !! .. py:attribute:: initialization_method :type: InitializationMethod .. py:property:: name :type: str The name of the model. :Returns: :obj:`str` The name of the model. .. !! processed by numpydoc !! .. py:property:: is_initialized :type: bool True if the model is initialized, False otherwise. :Returns: :obj:`bool` True if the model is initialized, False otherwise. .. !! processed by numpydoc !! .. py:property:: features :type: Optional[list[leaspy.utils.typing.FeatureType]] List of model features (`None` if not initialization). :Returns: : :obj:`list` [:obj:`FeatureType`], optional The features of the model, or None if not initialized. .. !! processed by numpydoc !! .. py:property:: dimension :type: Optional[int] Number of features. :Returns: :obj:`int`, optional The dimension of the model, or None if not initialized. .. !! processed by numpydoc !! .. py:method:: initialize(dataset = None) Initialize the model given a :class:`~leaspy.io.data.dataset.Dataset` and an initialization method. After calling this method :attr:`is_initialized` should be ``True`` and model should be ready for use. :Parameters: **dataset** : :class:`~leaspy.io.data.dataset.Dataset`, optional The dataset we want to initialize from. .. !! processed by numpydoc !! .. py:method:: save(path, **kwargs) Save model as json model parameter file. :Parameters: **path** : :obj:`str` or :obj:`Path` The path to store the model's parameters. **\*\*kwargs** : :obj:`dict` Additional parameters for writing. :Raises: :exc:`.LeaspyModelInputError` If the model is not initialized. .. !! processed by numpydoc !! .. py:method:: to_dict(**kwargs) Export model as a dictionary ready for export. :Returns: :obj:`KwargsType` The model instance serialized as a dictionary. .. !! processed by numpydoc !! .. py:method:: load(path_to_model_settings) :classmethod: Load a model from a json model parameter file. :Parameters: **path_to_model_settings** : :obj:`str` or :obj:`Path` The path to the model's parameters file. :Returns: :class:`~leasp.models.base.BaseModel` An instance of the model loaded from the file. :Raises: :exc:`.LeaspyModelInputError` If the model settings file is not found or cannot be read. .. !! processed by numpydoc !! .. py:method:: load_parameters(parameters) :abstractmethod: Load model parameters from a dictionary. :Parameters: **parameters** : :obj:`KwargsType` The parameters to load into the model. :Raises: NotImplementedError .. .. !! processed by numpydoc !! .. py:method:: fit(data = None, algorithm = None, algorithm_settings = None, algorithm_settings_path = None, **kwargs) Estimate the model's parameters for a given dataset and a given algorithm. These model's parameters correspond to the fixed-effects of the mixed-effects model. :Parameters: **data** : :obj:`pd.DataFrame` or :class:`~leaspy.io.Data` or :class:`~leaspy.io.Dataset`, optional Contains the information of the individuals, in particular the time-points :math:`(t_{i,j})` and the observations :math:`(y_{i,j})`. **algorithm** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName`, optional The name of the algorithm to use. Use this if you want to provide algorithm settings through kwargs. **algorithm_settings** : :class:`~leaspy.algo.AlgorithmSettings`, optional The algorithm settings to use. Use this if you want to customize algorithm settings through the :class:`~leaspy.algo.AlgorithmSettings` class. If provided, the fit will rely on these settings. **algorithm_settings_path** : :obj:`str` or :obj:`Path`, optional The path to the algorithm settings file. If provided, the settings from the file will be used instead of the settings provided. **\*\*kwargs** : :obj:`dict` Contains the algorithm's settings. .. !! processed by numpydoc !! .. py:method:: personalize(data = None, algorithm = None, algorithm_settings = None, algorithm_settings_path = None, **kwargs) Estimate individual parameters for each `ID` of a given dataset. These individual parameters correspond to the random-effects :math:`(z_{i,j})` of the mixed-effects model. :Parameters: **data** : :obj:`pd.DataFrame` or :class:`~leaspy.io.Data` or :class:`~leaspy.io.Dataset`, optional Contains the information of the individuals, in particular the time-points :math:`(t_{i,j})` and the observations :math:`(y_{i,j})`. **algorithm** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName`, optional The name of the algorithm to use. **algorithm_settings** : :class:`~leaspy.algo.AlgorithmSettings`, optional The algorithm settings to use. Use this if you want to customize algorithm settings through the :class:`~leaspy.algo.AlgorithmSettings` class. If provided, the fit will rely on these settings. **algorithm_settings_path** : :obj:`str` or :obj:`Path`, optional The path to the algorithm settings file. If provided, the settings from the file will be used instead of the settings provided. **\*\*kwargs** : :obj:`dict` Contains the algorithm's settings. :Returns: :class:`~leaspy.io.outputs.IndividualParameters` Individual parameters computed. .. !! processed by numpydoc !! .. py:method:: estimate(timepoints, individual_parameters, *, to_dataframe = None) Return the model values for individuals characterized by their individual parameters :math:`z_i` at time-points :math:`(t_{i,j})_j`. :Parameters: **timepoints** : :obj:`pd.MultiIndex` or :obj:`dict` [:obj:`IDType`, :obj:`list` [:obj:`float`]] Contains, for each individual, the time-points to estimate. It can be a unique time-point or a list of time-points. **individual_parameters** : :class:`~leaspy.io.IndividualParameters` Corresponds to the individual parameters of individuals. **to_dataframe** : :obj:`bool`, optional Whether to output a dataframe of estimations? If None: default is to be True if and only if timepoints is a `pandas.MultiIndex` :Returns: **individual_trajectory** : :obj:`pd.DataFrame` or :obj:`dict` [:obj:`IDType`, :obj:`np.ndarray`] Key: patient indices. Value: :class:`numpy.ndarray` of the estimated value, in the shape (number of timepoints, number of features) .. !! processed by numpydoc !! .. py:method:: compute_individual_trajectory(timepoints, individual_parameters) :abstractmethod: Compute the model values for an individual characterized by their individual parameters at given time-points. :Parameters: **timepoints** : :obj:`list` [:obj:`float`] The time-points at which to compute the model values. **individual_parameters** : :class:`~leaspy.io.IndividualParameters` The individual parameters of the individual. :Returns: :class:`torch.Tensor` The computed model values for the individual at the given time-points. :Raises: NotImplementedError If the method is not implemented in the subclass. .. !! processed by numpydoc !! .. py:method:: simulate(algorithm = None, algorithm_settings = None, algorithm_settings_path = None, **kwargs) Run the simulation pipeline using a leaspy model. This method simulates longitudinal data using the given leaspy model. It performs the following steps: - Retrieves individual parameters (IP) from fixed effects of the model. - Loads the specified Leaspy model. - Generates visit ages (timepoints) for each individual (based on specifications in visits_type) - Simulates observations at those visit ages. - Packages the result into a `Result` object, including simulated data, individual parameters, and the model's noise standard deviation. :Parameters: **algorithm** : :obj:`str` or :class:`~leaspy.algo.base.AlgorithmName`, optional The name of the algorithm to use. Use this if you want to provide algorithm settings through kwargs. **algorithm_settings** : :class:`~leaspy.algo.AlgorithmSettings`, optional The algorithm settings to use. Use this if you want to customize algorithm settings through the :class:`~leaspy.algo.AlgorithmSettings` class. If provided, the fit will rely on these settings. **algorithm_settings_path** : :obj:`str` or :obj:`Path`, optional The path to the algorithm settings file. If provided, the settings from the file will be used instead of the settings provided. **\*\*kwargs** : :obj:`dict` Contains the algorithm's settings. :Returns: **simulated_data** : :class:`~leaspy.io.outputs.result.Result` Contains the generated individual parameters & the corresponding generated scores. Returns empty Result if any required input is None. .. rubric:: Notes To generate a new subject, first we estimate the joined distribution of the individual parameters and the reparametrized baseline ages. Then, we randomly pick a new point from this distribution, which define the individual parameters & baseline age of our new subjects. Then, we generate the timepoints following the baseline age. Then, from the model and the generated timepoints and individual parameters, we compute the corresponding values estimations. Then, we add some noise to these estimations, which is the same noise-model as the one from your model by default. But, you may customize it by setting the `noise` keyword. .. rubric:: Examples Use a calibrated model & individual parameters to simulate new subjects similar to the ones you have: >>> from leaspy.models import LogisticModel >>> from leaspy.io.data import Data >>> from leaspy.datasets import load_dataset, load_leaspy_instance, load_individual_parameters >>> putamen_df = load_dataset("parkinson-putamen-train_and_test") >>> data = Data.from_dataframe(putamen_df.xs('train', level='SPLIT')) >>> leaspy_logistic = load_leaspy_instance("parkinson-putamen-train") >>> visits_params = { ... 'patient_number': 200, ... 'visit_type': "random", ... 'first_visit_mean': 0., ... 'first_visit_std': 0.4, ... 'time_follow_up_mean': 11, ... 'time_follow_up_std': 0.5, ... 'distance_visit_mean': 2/12, ... 'distance_visit_std': 0.75/12, ... 'min_spacing_between_visits': 1/365 ... } >>> simulated_data = model.simulate( algorithm="simulate", features=["MDS1_total", "MDS2_total", "MDS3_off_total", 'SCOPA_total','MOCA_total','REM_total','PUTAMEN_R','PUTAMEN_L','CAUDATE_R','CAUDATE_L'],visit_parameters= visits_params ) .. !! processed by numpydoc !!