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.

Parameters
model_namestr

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.

**kwargs

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

noise_modelstr

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

leaspy.models
Attributes
modelAbstractModel

Model used for computations, is an instance of AbstractModel.

typestr (read-only)

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

Methods

calibrate(data, settings)

Duplicates of the fit() method.

check_if_initialized()

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.

load(path_to_model_settings)

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.

model_factory.ModelFactory()

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.

abstract_multivariate_model.AbstractMultivariateModel(...)

Contains the common attributes & methods of the multivariate models.

multivariate_model.MultivariateModel(name, ...)

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

multivariate_parallel_model.MultivariateParallelModel(...)

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.

attributes_factory.AttributesFactory()

Return an Attributes class object based on the given parameters.

abstract_attributes.AbstractAttributes(name)

Abstract base class for attributes of models.

abstract_manifold_model_attributes.AbstractManifoldModelAttributes(...)

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.

logistic_parallel_attributes.LogisticParallelAttributes(...)

Attributes of leaspy logistic parallel models.

leaspy.models.utils.initialization: Initialization methods

Available methods to initialize model parameters before a fit.

model_initialization.initialize_parameters(...)

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_algo.AbstractAlgo(settings)

Abstract class containing common methods for all algorithm classes.

algo_factory.AlgoFactory()

Return the wanted algorithm given its name.

leaspy.algo.fit: Fit algorithms

Algorithms used to calibrate (fit) a model.

abstract_fit_algo.AbstractFitAlgo(settings)

Abstract class containing common method for all fit algorithm classes.

abstract_mcmc.AbstractFitMCMC(settings)

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

tensor_mcmcsaem.TensorMCMCSAEM(settings)

Main algorithm for MCMC-SAEM.

leaspy.algo.personalize: Personalization algorithms

Algorithms used to personalize a model to given subjects.

abstract_personalize_algo.AbstractPersonalizeAlgo(...)

Abstract class for personalize algorithm.

scipy_minimize.ScipyMinimize(settings)

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.

simulate.SimulationAlgorithm(settings)

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

constant_prediction_algo.ConstantPredictionAlgorithm(...)

ConstantPredictionAlgorithm is the algorithm that outputs a constant prediction

lme_fit.LMEFitAlgorithm(settings)

Calibration algorithm associated to LMEModel

lme_personalize.LMEPersonalizeAlgorithm(settings)

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.

loader.Loader()

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

data.Data()

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.

Methods

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_by_idx(idx)

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

to_dataframe([cofactors])

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

leaspy.io.settings: Settings classes

model_settings.ModelSettings(...)

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

algorithm_settings.AlgorithmSettings(name, ...)

Used to set the algorithms' settings.

outputs_settings.OutputsSettings(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.

Parameters
namestr
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.

Raises
LeaspyAlgoInputError

See also

leaspy.algo

Notes

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.

Example:

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

Format:

{algo_name: [
    (functional_condition_to_trigger_dynamic_setting(kwargs),
    {
        nested_keys_of_dynamic_setting: dynamic_value(kwargs)
    })
]}
Attributes
namestr

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.

parametersdict

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.

Methods

check_consistency()

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

load(path_to_algorithm_settings)

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

individual_parameters.IndividualParameters()

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.

collection_realization.CollectionRealization()

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:

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

LeaspyException

Base of all Leaspy exceptions.

LeaspyTypeError

Leaspy Exception, deriving from TypeError.

LeaspyInputError

Leaspy Exception, deriving from ValueError.

LeaspyDataInputError

Leaspy Input Error for data related issues.

LeaspyModelInputError

Leaspy Input Error for model related issues.

LeaspyAlgoInputError

Leaspy Input Error for algorithm related issues.

LeaspyIndividualParamsInputError

Leaspy Input Error for individual parameters related issues.