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.
|
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:
- model
AbstractModel
Model used for computations, is an instance of AbstractModel.
- typestr (read-only)
Name of the model - will be one of the names listed above.
- model
Methods
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 at time-points .
estimate_ages_from_biomarker_values
(...[, ...])For individuals characterized by their individual parameters , returns the age at which a given feature value is reached.
fit
(data, settings)Estimate the model's parameters 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.
|
Contains the common attributes & methods of the different models. |
|
Contains the common attributes & methods of the multivariate models. |
|
Base model class from which all |
|
ConstantModel is a benchmark model that predicts constant values (no matter what the patient's ages are). |
|
Generic model (temporary until |
|
LMEModel is a benchmark model that fits and personalize a linear mixed-effects model. |
Return the wanted model given its 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). |
|
Univariate (logistic or linear) model for a single variable of interest. |
leaspy.models.noise_models
: Noise Models
Available noise models in Leaspy.
|
Base class for a distribution family being able to sample "around" user-provided values. |
|
Base class for Gaussian noise models. |
|
Base class for Ordinal noise models. |
|
Base class for valid noise models that may be used in probabilistic models. |
|
Class implementing Bernoulli noise models. |
|
Class implementing diagonal Gaussian noise models. |
|
Class implementing scalar Gaussian noise models. |
|
Class implementing ordinal noise models (likelihood is based on PDF). |
|
Class implementing |
|
Factory for noise models. |
|
Serialize a given |
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. |
|
Attributes of leaspy linear models. |
|
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 |
|
Personalization algorithm associated to |
leaspy.samplers
: Samplers
Samplers used by the MCMC algorithms.
|
Abstract sampler class. |
|
Abstract class for samplers of population random variables. |
|
Abstract class for samplers of individual random variables. |
|
Gibbs sampler for individual variables. |
|
Gibbs sampler for population variables. |
|
Fast Gibbs sampler for population variables. |
|
Metropolis-Hastings sampler for population variables. |
|
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.
Contains static methods to load synthetic longitudinal dataset, calibrated |
leaspy.io
: Inputs / Outputs
Containers classes used as input / outputs in the Leaspy package.
leaspy.io.data
: Data containers
Main data container for a collection of individuals |
|
|
Data container based on |
- 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
dimension
intNumber of features
n_individuals
intNumber of individuals
n_visits
intTotal number of visits
cofactors
List[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
Used in |
|
|
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.
- 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:
See also
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.
- logs
OutputsSettings
, 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 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
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.
|
Abstract class for Realization. |
|
Class for realizations of individual variables. |
|
Class for realizations of population variables. |
|
Dictionary of abstract realizations providing an easy-to-use interface. |
|
Realizations of population and individual variables, stratified per variable type. |
|
Possible types for variables. |
|
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:
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. |
|
Leaspy Exception for errors relative to convergence. |