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)

  • 'ordinal' or 'ordinal_ranking': for ordinal data. WARNING : make sure your dataset only contains positive integers.

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.

batch_deltas_ordinalbool, optional

For logistic models with ordinal noise model only. If True, concatenates the deltas for each feature into a 2-dimensional Tensor “deltas” model parameter, which essentially allows faster sampling with new samplers. If False, each feature will induce a new model parameter “deltas_<feature_name>”. The default is False but it is preferable to switch to True when ordinal items have many levels or when there are many items (when fit takes too long basically). Batching deltas will speed up the sampling part of the MCMC SAEM by trading for less accuracy in the estimation of deltas.

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

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.

AbstractModel(name, *, noise_model[, ...])

Contains the common attributes & methods of the different models.

AbstractMultivariateModel(name, **kwargs)

Contains the common attributes & methods of the multivariate models.

BaseModel(name, **kwargs)

Base model class from which all Leaspy models should inherit.

ConstantModel(name, **kwargs)

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

GenericModel(name, **kwargs)

Generic model (temporary until AbstractModel is really abstract).

LMEModel(name, **kwargs)

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

ModelFactory()

Return the wanted model given its name.

MultivariateModel(name, **kwargs)

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

MultivariateParallelModel(name, **kwargs)

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

UnivariateModel(name, **kwargs)

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

leaspy.models.noise_models: Noise Models

Available noise models in Leaspy.

DistributionFamily([parameters])

Base class for a distribution family being able to sample "around" user-provided values.

AbstractGaussianNoiseModel([parameters, ...])

Base class for Gaussian noise models.

AbstractOrdinalNoiseModel([parameters, ...])

Base class for Ordinal noise models.

BaseNoiseModel([parameters])

Base class for valid noise models that may be used in probabilistic models.

BernoulliNoiseModel([parameters])

Class implementing Bernoulli noise models.

GaussianDiagonalNoiseModel([parameters, ...])

Class implementing diagonal Gaussian noise models.

GaussianScalarNoiseModel([parameters, ...])

Class implementing scalar Gaussian noise models.

OrdinalNoiseModel([parameters, max_levels])

Class implementing ordinal noise models (likelihood is based on PDF).

OrdinalRankingNoiseModel([parameters, ...])

Class implementing OrdinalRankingNoiseModel (likelihood is based on SF).

noise_model_factory(noise_model, **kws)

Factory for noise models.

export_noise_model(noise_model)

Serialize a given BaseNoiseModel as a dict.

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.samplers: Samplers

Samplers used by the MCMC algorithms.

AbstractSampler(name, shape, *[, ...])

Abstract sampler class.

AbstractPopulationSampler(name, shape, *[, ...])

Abstract class for samplers of population random variables.

AbstractIndividualSampler(name, shape, *, ...)

Abstract class for samplers of individual random variables.

IndividualGibbsSampler(name, shape, *, ...)

Gibbs sampler for individual variables.

PopulationGibbsSampler(name, shape, *, scale)

Gibbs sampler for population variables.

PopulationFastGibbsSampler(name, shape, *, scale)

Fast Gibbs sampler for population variables.

PopulationMetropolisHastingsSampler(name, ...)

Metropolis-Hastings sampler for population variables.

sampler_factory(sampler, variable_type, **kwargs)

Factory for Samplers.

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 for a collection of individuals

dataset.Dataset(data, *[, no_warning])

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

class Data

Main data container for a collection of individuals

It can be iterated over and sliced, both of these operations being applied to the underlying individuals attribute.

Attributes:
individualsDict[IDType, IndividualData]

Included individuals and their associated data

iter_to_idxDict[int, IDType]

Maps an integer index to the associated individual ID

headersList[FeatureType]

Feature names

dimensionint

Number of features

n_individualsint

Number of individuals

n_visitsint

Total number of visits

cofactorsList[FeatureType]

Feature names corresponding to cofactors

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_individual_values(indices, timepoints, ...)

Construct Data from a collection of individual data points

from_individuals(individuals, headers)

Construct Data from a list of individuals

load_cofactors(df, *[, cofactors])

Load cofactors from a pandas.DataFrame to the Data object

to_dataframe(*[, cofactors, reset_index])

Convert the Data object to a pandas.DataFrame

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'

**kwargsany
Depending on the algorithm you are setting up, various parameters are possible (not exhaustive):
  • seedint, optional, default None

    Used for stochastic algorithms.

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

  • use_jacobianbool, optional, default True

    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 True

    Used to display a progress bar during computation.

  • device: str or torch.device, optional

    Specifies on which device the algorithm will run. Only ‘cpu’ and ‘cuda’ are supported for this argument. Only 'mcmc_saem', 'mean_real' and 'mode_real' algorithms support this setting.

For the complete list of the available parameters for a given algorithm, please directly refer to its documentation.

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.

devicestr (or torch.device), optional, default ‘cpu’

Used to specify on which device the algorithm will run. This should either be: ‘cpu’ or ‘cuda’ and is only supported in specific algorithms (inheriting AlgoWithDeviceMixin). Note that specifying an indexed CUDA device (such as ‘cuda:1’) is not supported. In order to specify the precise cuda device index, one should use the CUDA_VISIBLE_DEVICES environment variable.

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

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

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.

AbstractRealization(name, shape, *[, ...])

Abstract class for Realization.

IndividualRealization(name, shape, *, ...)

Class for realizations of individual variables.

PopulationRealization(name, shape, *[, ...])

Class for realizations of population variables.

DictRealizations([realizations])

Dictionary of abstract realizations providing an easy-to-use interface.

CollectionRealization(*[, population, ...])

Realizations of population and individual variables, stratified per variable type.

VariableType(value)

Possible types for variables.

realization_factory(...)

Factory for Realizations.

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        RuntimeError
                    |         \            |
                    |           LeaspyConvergenceError
                   / \
     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.

LeaspyConvergenceError

Leaspy Exception for errors relative to convergence.