API Documentation

Full API documentation of the Leaspy Python package.

leaspy.api: Main API

The main class, from which you can instantiate and calibrate a model, personalize it to a given set a subjects, estimate trajectories and simulate synthetic data.

Leaspy(model_name, **kwargs)

Main API used to fit models, run algorithms and simulations.

class Leaspy(model_name: str, **kwargs)

Main API used to fit models, run algorithms and simulations. This is the main class of the Leaspy package.


The name of the model that will be used for the computations. The available models are:

  • 'logistic' - suppose that every modality follow a logistic curve across time.

  • 'logistic_parallel' - idem & suppose also that every modality have the same slope at inflexion point

  • 'linear' - suppose that every modality follow a linear curve across time.

  • 'univariate_logistic' - a ‘logistic’ model for a single modality.

  • 'univariate_linear' - idem with a ‘linear’ model.

  • 'constant' - benchmark model for constant predictions.

  • 'lme' - benchmark model for classical linear mixed-effects model.


Keyword arguments directly passed to the model for its initialization (through ModelFactory.model()). Refer to the corresponding model to know possible arguments.


For manifold-like models. Define the noise structure of the model, can be either:

  • 'gaussian_scalar': gaussian error, with same standard deviation for all features

  • 'gaussian_diagonal': gaussian error, with one standard deviation parameter per feature (default)

  • 'bernoulli': for binary data (Bernoulli realization)

source_dimensionint, optional

For multivariate models only. Set the degrees of freedom for _spatial_ variability. This number MUST BE strictly lower than the number of features. By default, this number is equal to square root of the number of features. One can interpret this hyperparameter as a way to reduce the dimension of inter-individual _spatial_ variability between progressions.

See also


Model used for computations, is an instance of AbstractModel.

typestr (read-only)

Name of the model - will be one of the names listed above.


calibrate(data, settings)

Duplicates of the fit() method.


Check if model is initialized.

estimate(timepoints, individual_parameters, *)

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

estimate_ages_from_biomarker_values(...[, ...])

For individuals characterized by their individual parameters z_{i}, returns the age t_{i,j} at which a given feature value y_{i,j,k} is reached.

fit(data, settings)

Estimate the model's parameters \theta for a given dataset and a given algorithm.


Instantiate a Leaspy object from json model parameter file or the corresponding dictionary.

personalize(data, settings, *[, return_noise])

From a model, estimate individual parameters for each ID of a given dataset.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

simulate(individual_parameters, data, settings)

Generate longitudinal synthetic patients data from a given model, a given collection of individual parameters and some given settings.

leaspy.models: Models

Available models in Leaspy.


Return the wanted model given its name.

abstract_model.AbstractModel(name, **kwargs)

Contains the common attributes & methods of the different models.

univariate_model.UnivariateModel(name, **kwargs)

Univariate (logistic or linear) model for a single variable of interest.


Contains the common attributes & methods of the multivariate models.

multivariate_model.MultivariateModel(name, ...)

Manifold model for multiple variables of interest (logistic or linear formulation).


Logistic model for multiple variables of interest, imposing same average evolution pace for all variables (logistic curves are only time-shifted).

lme_model.LMEModel(name, **kwargs)

LMEModel is a benchmark model that fits and personalize a linear mixed-effects model

constant_model.ConstantModel(name, **kwargs)

ConstantModel is a benchmark model that predicts constant values (no matter what the patient's ages are).

leaspy.models.utils.attributes: Models’ attributes

Attributes used by the models.


Return an Attributes class object based on the given parameters.


Abstract base class for attributes of models.


Abstract base class for attributes of leaspy manifold models.

linear_attributes.LinearAttributes(name, ...)

Attributes of leaspy linear models.

logistic_attributes.LogisticAttributes(name, ...)

Attributes of leaspy logistic models.


Attributes of leaspy logistic parallel models.

leaspy.models.utils.initialization: Initialization methods

Available methods to initialize model parameters before a fit.


Initialize the model's group parameters given its name & the scores of all subjects.

leaspy.algo: Algorithms

Contains all algorithms used in the package.


Abstract class containing common methods for all algorithm classes.


Return the wanted algorithm given its name.

leaspy.algo.fit: Fit algorithms

Algorithms used to calibrate (fit) a model.


Abstract class containing common method for all fit algorithm classes.


Abstract class containing common method for all fit algorithm classes based on Monte-Carlo Markov Chains (MCMC).


Main algorithm for MCMC-SAEM.

leaspy.algo.personalize: Personalization algorithms

Algorithms used to personalize a model to given subjects.


Abstract class for personalize algorithm.


Gradient descent based algorithm to compute individual parameters, i.e. personalize a model to a given set of subjects.

leaspy.algo.simulate: Simulation algorithms

Algorithm to simulate synthetic observations and individual parameters.


To simulate new data given existing one by learning the individual parameters joined distribution.

leaspy.algo.others: Other algorithms

Reference algorithms to use with reference models (for benchmarks).


ConstantPredictionAlgorithm is the algorithm that outputs a constant prediction


Calibration algorithm associated to LMEModel


Personalization algorithm associated to LMEModel

leaspy.algo.utils.samplers: Samplers

Samplers used by the MCMC algorithms.

abstract_sampler.AbstractSampler(info, ...)

Abstract sampler class.

gibbs_sampler.GibbsSampler(info, n_patients)

Gibbs sampler class.

leaspy.dataset: Datasets

Give access to some synthetic longitudinal observations mimicking cohort of subjects with neurodegenerative disorders, as well as calibrated models and computed individual parameters.


Contains static methods to load synthetic longitudinal dataset, calibrated Leaspy instances & IndividualParameters.

leaspy.io: Inputs / Outputs

Containers classes used as input / outputs in the Leaspy package.

leaspy.io.data: Data containers


Main data container, initialized from a csv file or a pandas.DataFrame.

dataset.Dataset(data[, model, algo])

Data container based on torch.Tensor, used to run algorithms.

class Data

Main data container, initialized from a csv file or a pandas.DataFrame.


from_csv_file(path, **kws)

Create a Data object from a CSV file.

from_dataframe(df, **kws)

Create a Data object from a pandas.DataFrame.

from_individuals(indices, timepoints, ...)

Create a Data class object from lists of ID, timepoints and the corresponding values.


Get the IndividualData of a an individual identified by its ID.

load_cofactors(df, cofactors)

Load cofactors from a pandas.DataFrame to the Data object


Return the subjects' observations in a pandas.DataFrame along their ID and ages at all visits.

leaspy.io.settings: Settings classes


Used in Leaspy.load() to create a Leaspy class object from a json file.

algorithm_settings.AlgorithmSettings(name, ...)

Used to set the algorithms' settings.


Used to create the logs folder to monitor the convergence of the calibration algorithm.

class AlgorithmSettings(name: str, **kwargs)

Used to set the algorithms’ settings. All parameters, except the choice of the algorithm, is set by default. The user can overwrite all default settings.

The algorithm’s name. Must be in:
  • For fit algorithms:
    • 'mcmc_saem'

    • 'lme_fit' (for LME model only)

  • For personalize algorithms:
    • 'scipy_minimize'

    • 'mean_real'

    • 'mode_real'

    • 'constant_prediction' (for constant model only)

    • 'lme_personalize' (for LME model only)

  • For simulate algorithms:
    • 'simulation'

model_initialization_methodstr, optional

For fit algorithms only, give a model initialization method, according to those possible in initialize_parameters().

algo_initialization_methodstr, optional

Personalize the algorithm initialization method, according to those possible for the given algorithm (refer to its documentation in leaspy.algo).

n_iterint, optional

Number of iteration. There is no stopping criteria for the all the MCMC SAEM algorithms.

n_burn_in_iterint, optional

Number of iteration during burning phase, used for the MCMC SAEM algorithms.

seedint, optional, default None

Used for stochastic algorithms.

use_jacobianbool, optional, default False

Used in scipy_minimize algorithm to perform a L-BFGS instead of a Powell algorithm.

n_jobsint, optional, default 1

Used in scipy_minimize algorithm to accelerate calculation with parallel derivation using joblib.

progress_barbool, optional, default False

Used to display a progress bar during computation.


See also



For developers: use _dynamic_default_parameters to dynamically set some default parameters, depending on other parameters that were set, while these dynamic parameters were not set.


you could want to set burn in iterations or annealing iterations as fractions of non-default number of iterations given.


{algo_name: [
        nested_keys_of_dynamic_setting: dynamic_value(kwargs)

The algorithm’s name.

model_initialization_methodstr, optional

For fit algorithms, give a model initialization method, according to those possible in initialize_parameters().

algo_initialization_methodstr, optional

Personalize the algorithm initialization method, according to those possible for the given algorithm (refer to its documentation in leaspy.algo).

seedint, optional, default None

Used for stochastic algorithms.


Contains the other parameters: n_iter, n_burn_in_iter, use_jacobian, n_jobs & progress_bar.

logsOutputsSettings, optional

Used to create a logs file during a model calibration containing convergence information.



Check internal consistency of algorithm settings and warn or raise a LeaspyAlgoInputError if not.


Instantiate a AlgorithmSettings object a from json file.

save(path, **kwargs)

Save an AlgorithmSettings object in a json file.

set_logs(path, **kwargs)

Use this method to monitor the convergence of a model callibration.

leaspy.io.outputs: Outputs classes


Data container for individual parameters, contains IDs, timepoints and observations values.

leaspy.io.realizations: Realizations classes

Internal classes used for random variables in MCMC algorithms.

realization.Realization(name, shape, ...)

Contains the realization of a given parameter.


Realizations of population and individual parameters.

leaspy.exceptions: Exceptions

Define custom Leaspy exceptions for better downstream handling.

Exceptions classes are nested so to handle in the most convenient way for users:

                   / \
     TypeError    /   \     ValueError
         |       /     \        |
  LeaspyTypeError      LeaspyInputError
                      /    |    |      \
                     /     |    |  LeaspyIndividualParamsInputError
                    /      |    |
LeaspyDataInputError       |  LeaspyAlgoInputError
For I/O operations, non-Leaspy specific errors may be raised, in particular:


Base of all Leaspy exceptions.


Leaspy Exception, deriving from TypeError.


Leaspy Exception, deriving from ValueError.


Leaspy Input Error for data related issues.


Leaspy Input Error for model related issues.


Leaspy Input Error for algorithm related issues.


Leaspy Input Error for individual parameters related issues.