leaspy.models.base¶

Classes¶

`Summary`	A structured summary of a Leaspy model.
`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 Summary[source]¶

A structured summary of a Leaspy model.

Provides programmatic access to model metadata, parameters, and training statistics. Calling model.summary() prints the summary; storing it in a variable allows access to individual attributes.

Use s.help() to see all available attributes and usage examples.

Examples

>>> model.summary()           # Prints the formatted summary
>>> s = model.summary()       # Store to access attributes
>>> s.algorithm               # 'mcmc_saem'
>>> s.seed                    # 42
>>> s.n_subjects              # 150
>>> s.get_param('tau_std')    # tensor([10.5])
>>> s.help()                  # Show all available attributes

name: str¶

model_type: str¶

dimension: int | None = None¶

features: list[str] | None = None¶

source_dimension: int | None = None¶

n_clusters: int | None = None¶

obs_models: list[str] | None = None¶

nll: float | None = None¶

training_info: dict¶

dataset_info: dict¶

parameters: dict[str, dict[str, Any]]¶

leaspy_version: str | None = None¶

property sources: list[str] | None¶

List of source names (e.g., [‘s0’, ‘s1’]) or None if not applicable.

Return type:: Optional[list[str]]

property clusters: list[str] | None¶

List of cluster names (e.g., [‘c0’, ‘c1’]) or None if not applicable.

Return type:: Optional[list[str]]

property algorithm: str | None¶

Name of the algorithm used for training.

Return type:: Optional[str]

property seed: int | None¶

Random seed used for training.

Return type:: Optional[int]

property n_iter: int | None¶

Number of iterations used for training.

Return type:: Optional[int]

property converged: bool | None¶

Whether the training algorithm converged.

Return type:: Optional[bool]

property n_subjects: int | None¶

Number of subjects in the training dataset.

Return type:: Optional[int]

property n_visits: int | None¶

Total number of visits in the training dataset.

Return type:: Optional[int]

property n_observations: int | None¶

Total number of observations in the training dataset.

Return type:: Optional[int]

get_param(name)[source]¶

Get a parameter value by name, searching across all categories.

Parameters:

namestr: The parameter name (e.g., ‘betas_mean’, ‘tau_std’, ‘noise_std’).

Returns:

The parameter value (typically a torch.Tensor), or None if not found.

Parameters:

name (str)

Return type:

Optional[Any]

help()[source]¶

Print information about available Summary attributes and their meanings.

Return type:: None

class InitializationMethod[source]¶

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[source]¶

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[FeatureType]¶

Abstractmethod:
Return type:: list[FeatureType]

List of model features (None if not initialization).

Raises:

NotImplementedError

Return type:

list[FeatureType]

property parameters: DictParamsTorch¶

Abstractmethod:
Return type:: DictParamsTorch

Dictionary of values for model parameters.

Returns:

DictParamsTorch

Raises:

NotImplementedError

Return type:

DictParamsTorch

property hyperparameters: DictParamsTorch¶

Abstractmethod:
Return type:: DictParamsTorch

Dictionary of values for model hyperparameters.

Returns:

DictParamsTorch

Raises:

NotImplementedError

Return type:

DictParamsTorch

abstractmethod save(path, **kwargs)[source]¶

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)[source]¶

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])

abstractmethod fit(data=None, algorithm=None, algorithm_settings=None, algorithm_settings_path=None, **kwargs)[source]¶

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:

By providing an instance of AlgorithmSettings
By providing a path to a serialized AlgorithmSettings
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:

data (Optional[Union[DataFrame, leaspy.io.data.dataset.Data, Dataset]])
algorithm (Optional[Union[str, AlgorithmName]])
algorithm_settings (Optional[AlgorithmSettings])
algorithm_settings_path (Optional[Union[str, Path]])

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]

abstractmethod personalize(data=None, algorithm=None, algorithm_settings=None, algorithm_settings_path=None, **kwargs)[source]¶

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:

data (Optional[Union[DataFrame, leaspy.io.data.dataset.Data, Dataset]])
algorithm (Optional[Union[str, AlgorithmName]])
algorithm_settings (Optional[AlgorithmSettings])
algorithm_settings_path (Optional[Union[str, Path]])

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)

abstractmethod estimate(timepoints, individual_parameters, *, to_dataframe=None)[source]¶

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:

timepoints (Union[MultiIndex, dict[IDType, list[float]]])
individual_parameters (IndividualParameters)
to_dataframe (Optional[bool])

Return type:

Union[DataFrame, dict[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)

abstractmethod simulate(individual_parameters, data=None, **kwargs)[source]¶

Run the simulation pipeline using a leaspy model.

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.

**kwargs : dict raise NotImplementedError

` 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:

individual_parameters (IndividualParameters)
data (Optional[Union[DataFrame, leaspy.io.data.dataset.Data, Dataset]])

class BaseModel(name, **kwargs)[source]¶

Bases: ModelInterface

Base model class from which all Leaspy models should inherit.

It implements the ModelInterface.

Parameters:: name (str)

dataset_info¶

training_info¶

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[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[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)[source]¶

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)[source]¶

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)[source]¶

Export model as a dictionary ready for export.

Returns:

KwargsType: The model instance serialized as a dictionary.

Return type:

KwargsType

classmethod load(path_to_model_settings)[source]¶

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])

abstractmethod load_parameters(parameters)[source]¶

Load model parameters from a dictionary.

Parameters:

parametersKwargsType: The parameters to load into the model.

Raises:

NotImplementedError

Parameters:

parameters (KwargsType)

Return type:

None

fit(data=None, algorithm=None, algorithm_settings=None, algorithm_settings_path=None, **kwargs)[source]¶

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:

data (Optional[Union[DataFrame, leaspy.io.data.dataset.Data, Dataset]])
algorithm (Optional[Union[str, AlgorithmName]])
algorithm_settings (Optional[AlgorithmSettings])
algorithm_settings_path (Optional[Union[str, Path]])

info()[source]¶

Print detailed information about the model configuration and training dataset.

Return type:: None

summary()[source]¶

Generate a structured summary of the model.

When called directly (e.g., model.summary()), prints a formatted summary. When stored in a variable, provides programmatic access to model attributes.

Returns:

Summary: A structured summary object.

Raises:

LeaspyModelInputError: If the model is not initialized or has no parameters.

Return type:

Summary

Examples

>>> model.summary()           # Prints the summary
>>> s = model.summary()       # Store to access attributes
>>> s.nll                     # Get specific value
>>> s.help()                  # Show available attributes

personalize(data=None, algorithm=None, algorithm_settings=None, algorithm_settings_path=None, **kwargs)[source]¶

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:

data (Optional[Union[DataFrame, leaspy.io.data.dataset.Data, Dataset]])
algorithm (Optional[Union[str, AlgorithmName]])
algorithm_settings (Optional[AlgorithmSettings])
algorithm_settings_path (Optional[Union[str, Path]])

Return type:

IndividualParameters

estimate(timepoints, individual_parameters, *, to_dataframe=None)[source]¶

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:

timepoints (Union[MultiIndex, dict[IDType, list[float]]])
individual_parameters (IndividualParameters)
to_dataframe (Optional[bool])

Return type:

Union[DataFrame, dict[IDType, ndarray]]

abstractmethod compute_individual_trajectory(timepoints, individual_parameters)[source]¶

Compute the model values for an individual characterized by their individual parameters at given time-points. Parameters ———- timepoints : list [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:

timepoints (list[float])
individual_parameters (IndividualParameters)

Return type:

Tensor

simulate(algorithm=None, algorithm_settings=None, algorithm_settings_path=None, **kwargs)[source]¶

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:

algorithm (Optional[Union[str, AlgorithmName]])
algorithm_settings (Optional[AlgorithmSettings])
algorithm_settings_path (Optional[Union[str, Path]])

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  )