leaspy.models.base#

Classes#

InitializationMethod

Possible initialization methods for Leaspy models.

ModelInterface

This is the public interface for Leaspy models.

BaseModel

Base model class from which all Leaspy models should inherit.

Module Contents#

class InitializationMethod#

Bases: str, enum.Enum

Possible initialization methods for Leaspy models.

Attributes:
DEFAULTstr

Default initialization method.

RANDOMstr

Random initialization method.

DEFAULT = 'default'#
RANDOM = 'random'#
class ModelInterface#

Bases: 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.

property name: str#
Abstractmethod:

Return type:

str

The name of the model.

Returns:
str
Raises:
NotImplementedError
Return type:

str

property is_initialized: bool#
Abstractmethod:

Return type:

bool

True if the model is initialized, False otherwise.

Returns:
bool
Raises:
NotImplementedError
Return type:

bool

property dimension: int#
Abstractmethod:

Return type:

int

Number of features.

Returns:
int
Raises:
NotImplementedError
Return type:

int

property features: list[leaspy.utils.typing.FeatureType]#
Abstractmethod:

Return type:

list[leaspy.utils.typing.FeatureType]

List of model features (None if not initialization).

Raises:
NotImplementedError
Return type:

list[leaspy.utils.typing.FeatureType]

property parameters: leaspy.utils.typing.DictParamsTorch#
Abstractmethod:

Return type:

leaspy.utils.typing.DictParamsTorch

Dictionary of values for model parameters.

Returns:
DictParamsTorch
Raises:
NotImplementedError
Return type:

leaspy.utils.typing.DictParamsTorch

property hyperparameters: leaspy.utils.typing.DictParamsTorch#
Abstractmethod:

Return type:

leaspy.utils.typing.DictParamsTorch

Dictionary of values for model hyperparameters.

Returns:
DictParamsTorch
Raises:
NotImplementedError
Return type:

leaspy.utils.typing.DictParamsTorch

abstract save(path, **kwargs)#

Save model as json model parameter file.

Parameters:
pathstr or Path

The path to store the model’s parameters.

**kwargsdict

Additional parameters for writing.

Raises:
NotImplementedError
Parameters:

path (Union[str, Path])

Return type:

None

classmethod load(path_to_model_settings)#
Abstractmethod:

Parameters:

path_to_model_settings (Union[str, Path])

Load a model from a json model parameter file.

Parameters:
path_to_model_settingsstr or Path

The path to the model’s parameters file.

Raises:
NotImplementedError
Parameters:

path_to_model_settings (Union[str, Path])

abstract fit(data=None, algorithm=None, algorithm_settings=None, algorithm_settings_path=None, **kwargs)#

Estimate the model’s parameters \(\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 AlgorithmSettings

  2. By providing a path to a serialized AlgorithmSettings

  3. By providing the algorithm name and parameters directly

If settings are provided in multiple ways, the order above will prevail.

Parameters:
datapd.DataFrame or Data or Dataset, optional

Contains the information of the individuals, in particular the time-points \((t_{i,j})\) and the observations \((y_{i,j})\).

algorithmstr or AlgorithmName,optional

The name of the algorithm to use.

Note

Use this if you want to provide algorithm settings through kwargs.

algorithm_settingsAlgorithmSettings, optional

The algorithm settings to use.

Note

Use this if you want to customize algorithm settings through the AlgorithmSettings class. If provided, the fit will rely on these settings.

algorithm_settings_pathstr or 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.

**kwargsdict

Contains the algorithm’s settings.

Raises:
NotImplementedError
Parameters:

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]
abstract 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 \((z_{i,j})\) of the mixed-effects model.

Parameters:
datapd.DataFrame or Data or Dataset, optional

Contains the information of the individuals, in particular the time-points \((t_{i,j})\) and the observations \((y_{i,j})\).

algorithmstr or AlgorithmName, optional

The name of the algorithm to use.

algorithm_settingsAlgorithmSettings, optional

The algorithm settings to use.

Note

Use this if you want to customize algorithm settings through the AlgorithmSettings class. If provided, the fit will rely on these settings.

algorithm_settings_pathstr or 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.

**kwargsdict

Contains the algorithm’s settings.

Returns:
ipsIndividualParameters

Individual parameters computed.

Raises:
NotImplementedError
Parameters:
Return type:

IndividualParameters

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)
abstract estimate(timepoints, individual_parameters, *, to_dataframe=None)#

Return the model values for individuals characterized by their individual parameters \(z_i\) at time-points \((t_{i,j})_j\).

Parameters:
timepointspd.MultiIndex or dict [IDType, list [float ] ]

Contains, for each individual, the time-points to estimate. It can be a unique time-point or a list of time-points.

individual_parametersIndividualParameters

Corresponds to the individual parameters of individuals.

to_dataframebool, 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_trajectorypd.MultiIndex or dict [IDType, list [float]]

Key: patient indices. Value: numpy.ndarray of the estimated value, in the shape (number of timepoints, number of features)

Raises:
NotImplementedError
Parameters:
Return type:

Union[DataFrame, dict[leaspy.utils.typing.IDType, ndarray]]

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)
abstract simulate(individual_parameters, data=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:
individual_parametersIndividualParameters

Individual parameters to use for the simulation.

datapd.DataFrame or Data or Dataset

Data object. If None, returns empty Result.

**kwargsdict

Additional arguments for algorithm settings.

Returns:
simulated_dataResult

Contains the generated individual parameters & the corresponding generated scores. Returns empty Result if any required input is None.

Raises:
NotImplementedError
Parameters:
class BaseModel(name, **kwargs)#

Bases: ModelInterface

Base model class from which all Leaspy models should inherit.

It implements the ModelInterface.

Parameters:

name (str)

initialization_method: InitializationMethod#
property name: str#

The name of the model.

Returns:
str

The name of the model.

Return type:

str

property is_initialized: bool#

True if the model is initialized, False otherwise.

Returns:
bool

True if the model is initialized, False otherwise.

Return type:

bool

property features: list[leaspy.utils.typing.FeatureType] | None#

List of model features (None if not initialization).

Returns:
: list [FeatureType], optional

The features of the model, or None if not initialized.

Return type:

Optional[list[leaspy.utils.typing.FeatureType]]

property dimension: int | None#

Number of features.

Returns:
int, optional

The dimension of the model, or None if not initialized.

Return type:

Optional[int]

initialize(dataset=None)#

Initialize the model given a Dataset and an initialization method.

After calling this method is_initialized should be True and model should be ready for use.

Parameters:
datasetDataset, optional

The dataset we want to initialize from.

Parameters:

dataset (Optional[Dataset])

Return type:

None

save(path, **kwargs)#

Save model as json model parameter file.

Parameters:
pathstr or Path

The path to store the model’s parameters.

**kwargsdict

Additional parameters for writing.

Raises:
LeaspyModelInputError

If the model is not initialized.

Parameters:

path (Union[str, Path])

Return type:

None

to_dict(**kwargs)#

Export model as a dictionary ready for export.

Returns:
KwargsType

The model instance serialized as a dictionary.

Return type:

leaspy.utils.typing.KwargsType

classmethod load(path_to_model_settings)#

Load a model from a json model parameter file.

Parameters:
path_to_model_settingsstr or Path

The path to the model’s parameters file.

Returns:
BaseModel

An instance of the model loaded from the file.

Raises:
LeaspyModelInputError

If the model settings file is not found or cannot be read.

Parameters:

path_to_model_settings (Union[str, Path])

abstract load_parameters(parameters)#

Load model parameters from a dictionary.

Parameters:
parametersKwargsType

The parameters to load into the model.

Raises:
NotImplementedError
Parameters:

parameters (leaspy.utils.typing.KwargsType)

Return type:

None

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:
datapd.DataFrame or Data or Dataset, optional

Contains the information of the individuals, in particular the time-points \((t_{i,j})\) and the observations \((y_{i,j})\).

algorithmstr or AlgorithmName, optional

The name of the algorithm to use. Use this if you want to provide algorithm settings through kwargs.

algorithm_settingsAlgorithmSettings, optional

The algorithm settings to use. Use this if you want to customize algorithm settings through the AlgorithmSettings class. If provided, the fit will rely on these settings.

algorithm_settings_pathstr or Path, optional

The path to the algorithm settings file. If provided, the settings from the file will be used instead of the settings provided.

**kwargsdict

Contains the algorithm’s settings.

Parameters:
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 \((z_{i,j})\) of the mixed-effects model.

Parameters:
datapd.DataFrame or Data or Dataset, optional

Contains the information of the individuals, in particular the time-points \((t_{i,j})\) and the observations \((y_{i,j})\).

algorithmstr or AlgorithmName, optional

The name of the algorithm to use.

algorithm_settingsAlgorithmSettings, optional

The algorithm settings to use. Use this if you want to customize algorithm settings through the AlgorithmSettings class. If provided, the fit will rely on these settings.

algorithm_settings_pathstr or Path, optional

The path to the algorithm settings file. If provided, the settings from the file will be used instead of the settings provided.

**kwargsdict

Contains the algorithm’s settings.

Returns:
IndividualParameters

Individual parameters computed.

Parameters:
Return type:

IndividualParameters

estimate(timepoints, individual_parameters, *, to_dataframe=None)#

Return the model values for individuals characterized by their individual parameters \(z_i\) at time-points \((t_{i,j})_j\).

Parameters:
timepointspd.MultiIndex or dict [IDType, list [float]]

Contains, for each individual, the time-points to estimate. It can be a unique time-point or a list of time-points.

individual_parametersIndividualParameters

Corresponds to the individual parameters of individuals.

to_dataframebool, 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_trajectorypd.DataFrame or dict [IDType, np.ndarray]

Key: patient indices. Value: numpy.ndarray of the estimated value, in the shape (number of timepoints, number of features)

Parameters:
Return type:

Union[DataFrame, dict[leaspy.utils.typing.IDType, ndarray]]

abstract compute_individual_trajectory(timepoints, individual_parameters)#

Compute the model values for an individual characterized by their individual parameters at given time-points.

Parameters:
timepointslist [float]

The time-points at which to compute the model values.

individual_parametersIndividualParameters

The individual parameters of the individual.

Returns:
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.

Parameters:
Return type:

Tensor

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:
algorithmstr or AlgorithmName, optional

The name of the algorithm to use. Use this if you want to provide algorithm settings through kwargs.

algorithm_settingsAlgorithmSettings, optional

The algorithm settings to use. Use this if you want to customize algorithm settings through the AlgorithmSettings class. If provided, the fit will rely on these settings.

algorithm_settings_pathstr or Path, optional

The path to the algorithm settings file. If provided, the settings from the file will be used instead of the settings provided.

**kwargsdict

Contains the algorithm’s settings.

Returns:
simulated_dataResult

Contains the generated individual parameters & the corresponding generated scores. Returns empty Result if any required input is None.

Parameters:

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.

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  )