leaspy.models package

Subpackages

Submodules

Module contents

class AbstractModel(name: str, *, noise_model: str | BaseNoiseModel | Dict[str, Any], fit_metrics: Dict[str, float] | None = None, **kwargs)

Bases: BaseModel

Contains the common attributes & methods of the different models.

Parameters:
namestr

The name of the model.

noise_modelstr or BaseNoiseModel

The noise model for observations (keyword-only parameter).

fit_metricsdict

Metrics that should be measured during the fit of the model and reported back to the user.

**kwargs

Hyperparameters for the model

Attributes:
is_initializedbool

Indicates if the model is initialized.

namestr

The model’s name.

featureslist of str

Names of the model features.

parametersdict

Contains the model’s parameters

noise_modelBaseNoiseModel

The noise model associated to the model.

regularization_distribution_factoryfunction dist params -> torch.distributions.Distribution

Factory of torch distribution to compute log-likelihoods for regularization (gaussian by default) (Not used anymore)

fit_metricsdict

Contains the metrics that are measured during the fit of the model and reported to the user.

Methods

check_noise_model_compatibility(model)

Raise a LeaspyModelInputError is the provided noise model isn't compatible with the model instance.

compute_canonical_loss_tensorized(data, ...)

Compute canonical loss, which depends on the noise model.

compute_individual_ages_from_biomarker_values(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters).

compute_individual_ages_from_biomarker_values_tensorized(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_attachment_tensorized(...)

Compute attachment term (per subject).

compute_individual_tensorized(timepoints, ...)

Compute the individual values at timepoints according to the model.

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

compute_jacobian_tensorized(timepoints, ...)

Compute the jacobian of the model w.r.t.

compute_model_sufficient_statistics(data, ...)

Compute sufficient statistics from a CollectionRealization.

compute_regularity_individual_parameters(...)

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

compute_regularity_individual_realization(...)

Compute regularity term for IndividualRealization.

compute_regularity_population_realization(...)

Compute regularity term for PopulationRealization.

compute_regularity_realization(realization)

Compute regularity term for a AbstractRealization instance.

compute_regularity_variable(value, mean, std, *)

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

compute_sufficient_statistics(data, realizations)

Compute sufficient statistics from realizations.

get_individual_random_variable_information()

Return the information on individual random variables relative to the model.

get_individual_variable_names()

Get the names of the individual variables of the model.

get_population_random_variable_information()

Return the information on population random variables relative to the model.

get_population_variable_names()

Get the names of the population variables of the model.

initialize(dataset[, method])

Initialize the model given a Dataset and an initialization method.

load_hyperparameters(hyperparameters)

Load model's hyperparameters.

load_parameters(parameters)

Instantiate or update the model's parameters.

move_to_device(device)

Move a model and its relevant attributes to the specified torch.device.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

time_reparametrization(timepoints, xi, tau)

Tensorized time reparametrization formula.

to_dict()

Export model as a dictionary ready for export.

update_model_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_model_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

update_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
check_noise_model_compatibility(model: BaseNoiseModel) → None

Raise a LeaspyModelInputError is the provided noise model isn’t compatible with the model instance.

This needs to be implemented in subclasses.

Parameters:
modelBaseNoiseModel

The noise model with which to check compatibility.

compute_canonical_loss_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type=None) → Tensor

Compute canonical loss, which depends on the noise model.

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_inddict

Contain the individual parameters.

attribute_typestr or None (default)

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
losstorch.Tensor

shape = * (depending on noise-model, always summed over individuals & visits)

compute_individual_ages_from_biomarker_values(value: float | List[float], individual_parameters: Dict[str, Any], feature: str | None = None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters).

Consistency checks are done in the main API layer.

Parameters:
valuescalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the biomarker value(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (1, n_values).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

abstract compute_individual_ages_from_biomarker_values_tensorized(value: Tensor, individual_parameters: Dict[str, Tensor], feature: str | None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_attachment_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type: str | None = None) → Tensor

Compute attachment term (per subject).

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_indDictParamsTorch

Contain the individual parameters.

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
attachmenttorch.Tensor

Negative Log-likelihood, shape = (n_subjects,).

abstract compute_individual_tensorized(timepoints: Tensor, individual_parameters: Dict[str, Tensor], *, attribute_type: str | None = None) → Tensor

Compute the individual values at timepoints according to the model.

Parameters:
timepointstorch.Tensor

Timepoints tensor of shape (n_individuals, n_timepoints).

individual_parametersdict [ param_name: str, torch.Tensor ]

The tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
torch.Tensor of shape (n_individuals, n_timepoints, n_features)
compute_individual_trajectory(timepoints, individual_parameters: Dict[str, Any], *, skip_ips_checks: bool = False) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

skip_ips_checksbool (default: False)

Flag to skip consistency/compatibility checks and tensorization of individual_parameters when it was done earlier (speed-up).

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s) Shape of tensor is (1, n_tpts, n_features).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

LeaspyIndividualParamsInputError

if invalid individual parameters.

abstract compute_jacobian_tensorized(timepoints: Tensor, individual_parameters: Dict[str, Tensor], *, attribute_type: str | None = None) → Dict[str, Tensor]

Compute the jacobian of the model w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

abstract compute_model_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from a CollectionRealization.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor ]
compute_regularity_individual_parameters(individual_parameters: Dict[str, Tensor], *, include_constant: bool = False) → Tuple[Dict[str, Tensor], Dict[str, Tensor]]

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

Parameters:
individual_parametersdict [ str, torch.Tensor ]

Individual parameters as a dict of tensors of shape (n_ind, n_dims_param).

include_constantbool, optional

Whether to include a constant term or not. Default=False.

Returns:
regularitydict [ param_name: str, torch.Tensor ]

Regularity of the patient(s) corresponding to the given individual parameters. Tensors have shape (n_individuals).

regularity_gradsdict [ param_name: str, torch.Tensor ]

Gradient of regularity term with respect to individual parameters. Tensors have shape (n_individuals, n_dims_param).

compute_regularity_individual_realization(realization: IndividualRealization) → Tensor

Compute regularity term for IndividualRealization.

Parameters:
realizationIndividualRealization
Returns:
torch.Tensor of the same shape as IndividualRealization.tensor
compute_regularity_population_realization(realization: PopulationRealization) → Tensor

Compute regularity term for PopulationRealization.

Parameters:
realizationPopulationRealization
Returns:
torch.Tensor of the same shape as PopulationRealization.tensor
compute_regularity_realization(realization: AbstractRealization) → Tensor

Compute regularity term for a AbstractRealization instance.

Parameters:
realizationAbstractRealization
Returns:
torch.Tensor of the same shape as AbstractRealization.tensor
compute_regularity_variable(value: Tensor, mean: Tensor, std: Tensor, *, include_constant: bool = True, with_gradient: bool = False) → Tensor | Tuple[Tensor, Tensor]

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

Note

TODO: should be encapsulated in a RandomVariableSpecification class together with other specs of RV.

Parameters:
value, mean, stdtorch.Tensor of same shapes
include_constantbool (default True)

Whether we include or not additional terms constant with respect to value.

with_gradientbool (default False)

Whether we also return the gradient of regularity term with respect to value.

Returns:
torch.Tensor of same shape than input
compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from realizations.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor]
property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
abstract get_individual_random_variable_information() → Dict[str, Any]

Return the information on individual random variables relative to the model.

Returns:
DictParams

The information on the individual random variables.

get_individual_variable_names() → List[str]

Get the names of the individual variables of the model.

Returns:
list of str
abstract get_population_random_variable_information() → Dict[str, Any]

Return the information on population random variables relative to the model.

Returns:
DictParams

The information on the population random variables.

get_population_variable_names() → List[str]

Get the names of the population variables of the model.

Returns:
list of str
initialize(dataset: Dataset, method: str = 'default') → None

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

The dataset we want to initialize from.

methodstr

A custom method to initialize the model

abstract load_hyperparameters(hyperparameters: Dict[str, Any]) → None

Load model’s hyperparameters.

Parameters:
hyperparametersdict [ str, Any ]

Contains the model’s hyperparameters.

Raises:
LeaspyModelInputError

If any of the consistency checks fail.

load_parameters(parameters: Dict[str, Any]) → None

Instantiate or update the model’s parameters.

Parameters:
parametersdict [ str, Any ]

Contains the model’s parameters.

move_to_device(device: device) → None

Move a model and its relevant attributes to the specified torch.device.

Parameters:
devicetorch.device
property noise_model: BaseNoiseModel
save(path: str, **kwargs) → None

Save Leaspy object as json model parameter file.

TODO move logic upstream?

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for AbstractModel.to_dict() child method and json.dump function (default to indent=2).

static time_reparametrization(timepoints: Tensor, xi: Tensor, tau: Tensor) → Tensor

Tensorized time reparametrization formula.

Warning

Shapes of tensors must be compatible between them.

Parameters:
timepointstorch.Tensor

Timepoints to reparametrize.

xitorch.Tensor

Log-acceleration of individual(s).

tautorch.Tensor

Time-shift(s).

Returns:
torch.Tensor of same shape as timepoints
abstract to_dict() → Dict[str, Any]

Export model as a dictionary ready for export.

Returns:
KwargsType

The model instance serialized as a dictionary.

abstract update_model_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
abstract update_model_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class AbstractMultivariateModel(name: str, **kwargs)

Bases: OrdinalModelMixin, AbstractModel

Contains the common attributes & methods of the multivariate models.

Parameters:
namestr

Name of the model.

**kwargs

Hyperparameters for the model (including noise_model).

Raises:
LeaspyModelInputError

If inconsistent hyperparameters.

Attributes:
dimension

The dimension of the model.

features
is_ordinal

Property to check if the model is of ordinal sub-type.

is_ordinal_ranking

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

noise_model
ordinal_infos

Property to return the ordinal info dictionary.

Methods

check_noise_model_compatibility(model)

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(...)

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data, ...)

Compute canonical loss, which depends on the noise model.

compute_individual_ages_from_biomarker_values(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters).

compute_individual_ages_from_biomarker_values_tensorized(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_attachment_tensorized(...)

Compute attachment term (per subject).

compute_individual_tensorized(timepoints, ...)

Compute the individual trajectories.

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

compute_jacobian_tensorized(timepoints, ...)

Compute the jacobian of the model w.r.t.

compute_mean_traj(timepoints, *[, ...])

Compute trajectory of the model with individual parameters being the group-average ones.

compute_model_sufficient_statistics(data, ...)

Compute sufficient statistics from a CollectionRealization.

compute_ordinal_model_sufficient_statistics(...)

Compute the sufficient statistics given realizations.

compute_ordinal_pdf_from_ordinal_sf(ordinal_sf)

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

compute_regularity_individual_parameters(...)

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

compute_regularity_individual_realization(...)

Compute regularity term for IndividualRealization.

compute_regularity_population_realization(...)

Compute regularity term for PopulationRealization.

compute_regularity_realization(realization)

Compute regularity term for a AbstractRealization instance.

compute_regularity_variable(value, mean, std, *)

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

compute_sufficient_statistics(data, realizations)

Compute sufficient statistics from realizations.

get_additional_ordinal_population_random_variable_information()

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information()

Return the information on individual random variables relative to the model.

get_individual_variable_names()

Get the names of the individual variables of the model.

get_ordinal_parameters_updates_from_sufficient_statistics(...)

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information()

Return the information on population random variables relative to the model.

get_population_variable_names()

Get the names of the population variables of the model.

initialize(dataset[, method])

Overloads base initialization of model (base method takes care of features consistency checks).

initialize_MCMC_toolbox()

Initialize MCMC toolbox for calibration of model.

load_hyperparameters(hyperparameters)

Updates all model hyperparameters from the provided hyperparameters.

load_parameters(parameters)

Updates all model parameters from the provided parameters.

move_to_device(device)

Move a model and its relevant attributes to the specified torch.device.

postprocess_model_estimation(estimation, *)

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

time_reparametrization(timepoints, xi, tau)

Tensorized time reparametrization formula.

to_dict(*[, with_mixing_matrix])

Export Leaspy object as dictionary ready for JSON saving.

update_MCMC_toolbox(vars_to_update, realizations)

Update the MCMC toolbox with a CollectionRealization of model population parameters.

update_model_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_model_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

update_ordinal_population_random_variable_information(...)

Update (in-place) the provided variable information dictionary.

update_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
check_noise_model_compatibility(model: BaseNoiseModel) → None

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(model_or_model_grad: Tensor) → Tensor

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type=None) → Tensor

Compute canonical loss, which depends on the noise model.

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_inddict

Contain the individual parameters.

attribute_typestr or None (default)

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
losstorch.Tensor

shape = * (depending on noise-model, always summed over individuals & visits)

compute_individual_ages_from_biomarker_values(value: float | List[float], individual_parameters: Dict[str, Any], feature: str | None = None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters).

Consistency checks are done in the main API layer.

Parameters:
valuescalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the biomarker value(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (1, n_values).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

abstract compute_individual_ages_from_biomarker_values_tensorized(value: Tensor, individual_parameters: Dict[str, Tensor], feature: str | None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_attachment_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type: str | None = None) → Tensor

Compute attachment term (per subject).

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_indDictParamsTorch

Contain the individual parameters.

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
attachmenttorch.Tensor

Negative Log-likelihood, shape = (n_subjects,).

abstract compute_individual_tensorized(timepoints: Tensor, individual_parameters: Dict[str, Tensor], *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_trajectory(timepoints, individual_parameters: Dict[str, Any], *, skip_ips_checks: bool = False) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

skip_ips_checksbool (default: False)

Flag to skip consistency/compatibility checks and tensorization of individual_parameters when it was done earlier (speed-up).

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s) Shape of tensor is (1, n_tpts, n_features).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

LeaspyIndividualParamsInputError

if invalid individual parameters.

abstract compute_jacobian_tensorized(timepoints: Tensor, individual_parameters: Dict[str, Tensor], *, attribute_type: str | None = None) → Dict[str, Tensor]

Compute the jacobian of the model w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_mean_traj(timepoints: Tensor, *, attribute_type: str | None = None) → Tensor

Compute trajectory of the model with individual parameters being the group-average ones.

TODO check dimensions of io?

Parameters:
timepointstorch.Tensor of shape (1, n_timepoints)
attribute_typestr or None

If a string, should be “MCMC”.

Returns:
torch.Tensor of shape (1, n_timepoints, dimension)

The group-average values at given timepoints.

abstract compute_model_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from a CollectionRealization.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor ]
compute_ordinal_model_sufficient_statistics(realizations: CollectionRealization) → Dict[str, Tensor]

Compute the sufficient statistics given realizations.

static compute_ordinal_pdf_from_ordinal_sf(ordinal_sf: Tensor, dim_ordinal_levels: int = 3) → Tensor

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

Parameters:
ordinal_sftorch.FloatTensor

Survival function values : ordinal_sf[…, l] is the proba to be superior or equal to l+1 Dimensions are: * 0=individual * 1=visit * 2=feature * 3=ordinal_level [l=0..L-1] * [4=individual_parameter_dim_when_gradient]

dim_ordinal_levelsint, default = 3

The dimension of the tensor where the ordinal levels are.

Returns:
ordinal_pdftorch.FloatTensor (same shape as input, except for dimension 3 which has one more element)

ordinal_pdf[…, l] is the proba to be equal to l (l=0..L)

compute_regularity_individual_parameters(individual_parameters: Dict[str, Tensor], *, include_constant: bool = False) → Tuple[Dict[str, Tensor], Dict[str, Tensor]]

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

Parameters:
individual_parametersdict [ str, torch.Tensor ]

Individual parameters as a dict of tensors of shape (n_ind, n_dims_param).

include_constantbool, optional

Whether to include a constant term or not. Default=False.

Returns:
regularitydict [ param_name: str, torch.Tensor ]

Regularity of the patient(s) corresponding to the given individual parameters. Tensors have shape (n_individuals).

regularity_gradsdict [ param_name: str, torch.Tensor ]

Gradient of regularity term with respect to individual parameters. Tensors have shape (n_individuals, n_dims_param).

compute_regularity_individual_realization(realization: IndividualRealization) → Tensor

Compute regularity term for IndividualRealization.

Parameters:
realizationIndividualRealization
Returns:
torch.Tensor of the same shape as IndividualRealization.tensor
compute_regularity_population_realization(realization: PopulationRealization) → Tensor

Compute regularity term for PopulationRealization.

Parameters:
realizationPopulationRealization
Returns:
torch.Tensor of the same shape as PopulationRealization.tensor
compute_regularity_realization(realization: AbstractRealization) → Tensor

Compute regularity term for a AbstractRealization instance.

Parameters:
realizationAbstractRealization
Returns:
torch.Tensor of the same shape as AbstractRealization.tensor
compute_regularity_variable(value: Tensor, mean: Tensor, std: Tensor, *, include_constant: bool = True, with_gradient: bool = False) → Tensor | Tuple[Tensor, Tensor]

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

Note

TODO: should be encapsulated in a RandomVariableSpecification class together with other specs of RV.

Parameters:
value, mean, stdtorch.Tensor of same shapes
include_constantbool (default True)

Whether we include or not additional terms constant with respect to value.

with_gradientbool (default False)

Whether we also return the gradient of regularity term with respect to value.

Returns:
torch.Tensor of same shape than input
compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from realizations.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor]
property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_additional_ordinal_population_random_variable_information() → Dict[str, Any]

Return the information of additional population random variables for the ordinal model.

abstract get_individual_random_variable_information() → Dict[str, Any]

Return the information on individual random variables relative to the model.

Returns:
DictParams

The information on the individual random variables.

get_individual_variable_names() → List[str]

Get the names of the individual variables of the model.

Returns:
list of str
get_ordinal_parameters_updates_from_sufficient_statistics(sufficient_statistics: Dict[str, Tensor]) → Dict[str, Tensor]

Return a dictionary computed from provided sufficient statistics for updating the parameters.

abstract get_population_random_variable_information() → Dict[str, Any]

Return the information on population random variables relative to the model.

Returns:
DictParams

The information on the population random variables.

get_population_variable_names() → List[str]

Get the names of the population variables of the model.

Returns:
list of str
initialize(dataset: Dataset, method: str = 'default') → None

Overloads base initialization of model (base method takes care of features consistency checks).

Parameters:
datasetDataset

Input Dataset from which to initialize the model.

methodstr, optional

The initialization method to be used. Default=’default’.

abstract initialize_MCMC_toolbox() → None

Initialize MCMC toolbox for calibration of model.

property is_ordinal: bool

Property to check if the model is of ordinal sub-type.

property is_ordinal_ranking: bool

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

load_hyperparameters(hyperparameters: Dict[str, Any]) → None

Updates all model hyperparameters from the provided hyperparameters.

Parameters:
hyperparametersKwargsType

The hyperparameters to be loaded.

load_parameters(parameters: Dict[str, Any]) → None

Updates all model parameters from the provided parameters.

Parameters:
parametersKwargsType

The parameters to be loaded.

move_to_device(device: device) → None

Move a model and its relevant attributes to the specified torch.device.

Parameters:
devicetorch.device
property noise_model: BaseNoiseModel
property ordinal_infos: dict | None

Property to return the ordinal info dictionary.

postprocess_model_estimation(estimation: ndarray, *, ordinal_method: str = 'MLE', **kws) → ndarray | Dict[Hashable, ndarray]

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

Parameters:
estimationnumpy.ndarray[float]

The raw estimated values by model (from compute_individual_trajectory)

ordinal_methodstr

<!> Only used for ordinal models. * ‘MLE’ or ‘maximum_likelihood’ returns maximum likelihood estimator for each point (int) * ‘E’ or ‘expectation’ returns expectation (float) * ‘P’ or ‘probabilities’ returns probabilities of all-possible levels for a given feature:

{feature_name: array[float]<0..max_level_ft>}

**kws

Some extra keywords arguments that may be handled in the future.

Returns:
numpy.ndarray[float] or dict[str, numpy.ndarray[float]]

Post-processed values. In case using ‘probabilities’ mode, the values are a dictionary with keys being: (feature_name: str, feature_level: int<0..max_level_for_feature>) Otherwise it is a standard numpy.ndarray corresponding to different model features (in order)

save(path: str, **kwargs) → None

Save Leaspy object as json model parameter file.

TODO move logic upstream?

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for AbstractModel.to_dict() child method and json.dump function (default to indent=2).

static time_reparametrization(timepoints: Tensor, xi: Tensor, tau: Tensor) → Tensor

Tensorized time reparametrization formula.

Warning

Shapes of tensors must be compatible between them.

Parameters:
timepointstorch.Tensor

Timepoints to reparametrize.

xitorch.Tensor

Log-acceleration of individual(s).

tautorch.Tensor

Time-shift(s).

Returns:
torch.Tensor of same shape as timepoints
to_dict(*, with_mixing_matrix: bool = True) → Dict[str, Any]

Export Leaspy object as dictionary ready for JSON saving.

Parameters:
with_mixing_matrixbool (default True)

Save the mixing matrix in the exported file in its ‘parameters’ section.

Warning

It is not a real parameter and its value will be overwritten at model loading (orthonormal basis is recomputed from other “true” parameters and mixing matrix is then deduced from this orthonormal basis and the betas)! It was integrated historically because it is used for convenience in browser webtool and only there…

Returns:
KwargsType

The object as a dictionary.

abstract update_MCMC_toolbox(vars_to_update: Set[str], realizations: CollectionRealization) → None

Update the MCMC toolbox with a CollectionRealization of model population parameters.

Parameters:
vars_to_updateset of str

Names of the population parameters to update in MCMC toolbox.

realizationsCollectionRealization

All the realizations to update MCMC toolbox with.

abstract update_model_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
abstract update_model_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_ordinal_population_random_variable_information(variables_info: Dict[str, Any]) → None

Update (in-place) the provided variable information dictionary.

Nota: this is needed due to different signification of v0 in ordinal model (common per-level velocity)

Parameters:
variables_infoDictParams

The variables information to be updated with ordinal logic.

update_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class BaseModel(name: str, **kwargs)

Bases: ABC

Base model class from which all Leaspy models should inherit.

It defines the interface that a model should implement to be compatible with Leaspy.

Parameters:
namestr

The name of the model.

**kwargs

Hyperparameters of the model

Attributes:
namestr

The name of the model.

is_initializedbool

True``if the model is initialized, ``False otherwise.

featureslist of str

List of model features (None if not initialization).

dimensionint

The dimension of the model.

Methods

initialize(dataset[, method])

Initialize the model given a Dataset and an initialization method.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
initialize(dataset: Dataset, method: str = 'default') → None

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

The dataset we want to initialize from.

methodstr

A custom method to initialize the model

abstract save(path: str, **kwargs) → None

Save Leaspy object as json model parameter file.

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Additional parameters for writing.

validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class ConstantModel(name: str, **kwargs)

Bases: GenericModel

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

These constant values depend on the algorithm setting and the patient’s values provided during calibration.

It could predict:

  • last: last value seen during calibration (even if NaN).

  • last_known: last non NaN value seen during calibration.

  • max: maximum (=worst) value seen during calibration.

  • mean: average of values seen during calibration.

Warning

Depending on features, the last_known / max value may correspond to different visits.

Warning

For a given feature, value will be NaN if and only if all values for this feature were NaN.

Parameters:
namestr

The model’s name.

**kwargs

Hyperparameters for the model. None supported for now.

See also

ConstantPredictionAlgorithm
Attributes:
namestr

The model’s name.

is_initializedbool

Always True (no true initialization needed for constant model).

featureslist of str

List of the model features. Unlike most models features will be determined at personalization only (because it does not needed any fit).

dimensionint

The dimension of the model.

parametersdict

The model has no parameters: empty dictionary. The prediction_type parameter should be defined during personalization. Example:

>>> AlgorithmSettings('constant_prediction', prediction_type='last_known')

Methods

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

get_hyperparameters(*[, with_features, ...])

Get all model hyperparameters.

hyperparameters_ok()

Check all model hyperparameters are ok.

initialize(dataset[, method])

Initialize the model given a Dataset and an initialization method.

load_hyperparameters(hyperparameters, *[, ...])

Load model hyperparameters from a dict.

load_parameters(parameters, *[, list_converter])

Instantiate or update the model's parameters.

save(path, **kwargs)

Save Leaspy object as JSON model parameter file.

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
compute_individual_trajectory(timepoints: Tensor, individual_parameters: dict) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict [ str, Any]

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s). The shape of the tensor is (1, n_tpts, n_features).

property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_hyperparameters(*, with_features=True, with_properties=True, default=None) → Dict[str, Any]

Get all model hyperparameters.

Parameters:
with_features, with_propertiesbool (default True)

Whether to include features and respectively all _properties (i.e. _dynamic_ hyperparameters) in the returned dictionary.

defaultAny

Default value is something is an hyperparameter is missing (should not!).

Returns:
:obj:`dict` { hyperparam_namestr -> hyperparam_valueAny }
hyperparameters_ok() → bool

Check all model hyperparameters are ok.

Returns:
bool
initialize(dataset: Dataset, method: str = 'default') → None

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

The dataset we want to initialize from.

methodstr

A custom method to initialize the model

load_hyperparameters(hyperparameters: Dict[str, Any], *, with_defaults: bool = False) → None

Load model hyperparameters from a dict.

Parameters:
hyperparametersdict [ str, Any]

Contains the model’s hyperparameters.

with_defaultsbool (default False)

If True, it also resets hyperparameters that are part of the model but not included in hyperparameters to their default value.

Raises:
LeaspyModelInputError

If inconsistent hyperparameters.

load_parameters(parameters, *, list_converter=<built-in function array>) → None

Instantiate or update the model’s parameters.

Parameters:
parametersdict

Contains the model’s parameters.

list_convertercallable

The function to convert list objects.

save(path: str, **kwargs) → None

Save Leaspy object as JSON model parameter file.

Default save method: it can be overwritten in child class but should be generic…

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for json.dump method.

validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class GenericModel(name: str, **kwargs)

Bases: BaseModel

Generic model (temporary until AbstractModel is really abstract).

TODO: change naming after AbstractModel was renamed?

Parameters:
namestr

The name of the model.

**kwargs

Hyperparameters of the model.

Attributes:
namestr

The name of the model.

is_initializedbool

True if the model is initialized, False otherwise.

featureslist of str

List of model features (None if not initialization).

dimensionint (read-only)

The dimension of the model.

parametersdict

Contains internal parameters of the model.

Methods

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

get_hyperparameters(*[, with_features, ...])

Get all model hyperparameters.

hyperparameters_ok()

Check all model hyperparameters are ok.

initialize(dataset[, method])

Initialize the model given a Dataset and an initialization method.

load_hyperparameters(hyperparameters, *[, ...])

Load model hyperparameters from a dict.

load_parameters(parameters, *[, list_converter])

Instantiate or update the model's parameters.

save(path, **kwargs)

Save Leaspy object as JSON model parameter file.

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
abstract compute_individual_trajectory(timepoints, individual_parameters: dict) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict [ str, Any]

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s). The shape of the tensor is (1, n_tpts, n_features).

property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_hyperparameters(*, with_features=True, with_properties=True, default=None) → Dict[str, Any]

Get all model hyperparameters.

Parameters:
with_features, with_propertiesbool (default True)

Whether to include features and respectively all _properties (i.e. _dynamic_ hyperparameters) in the returned dictionary.

defaultAny

Default value is something is an hyperparameter is missing (should not!).

Returns:
:obj:`dict` { hyperparam_namestr -> hyperparam_valueAny }
hyperparameters_ok() → bool

Check all model hyperparameters are ok.

Returns:
bool
initialize(dataset: Dataset, method: str = 'default') → None

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

The dataset we want to initialize from.

methodstr

A custom method to initialize the model

load_hyperparameters(hyperparameters: Dict[str, Any], *, with_defaults: bool = False) → None

Load model hyperparameters from a dict.

Parameters:
hyperparametersdict [ str, Any]

Contains the model’s hyperparameters.

with_defaultsbool (default False)

If True, it also resets hyperparameters that are part of the model but not included in hyperparameters to their default value.

Raises:
LeaspyModelInputError

If inconsistent hyperparameters.

load_parameters(parameters, *, list_converter=<built-in function array>) → None

Instantiate or update the model’s parameters.

Parameters:
parametersdict

Contains the model’s parameters.

list_convertercallable

The function to convert list objects.

save(path: str, **kwargs) → None

Save Leaspy object as JSON model parameter file.

Default save method: it can be overwritten in child class but should be generic…

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for json.dump method.

validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class LMEModel(name: str, **kwargs)

Bases: GenericModel

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

The model specification is the following:

y_{ij} = fixed_{intercept} + random_{intercept_i} + (fixed_{slopeAge} + random_{slopeAge_i}) * age_{ij} + \epsilon_{ij}

with:

  • y_{ij}: value of the feature of the i-th subject at his j-th visit,

  • age_{ij}: age of the i-th subject at his j-th visit.

  • \epsilon_{ij}: residual Gaussian noise (independent between visits)

Warning

This model must be fitted on one feature only (univariate model).

TODO? should inherit from AbstractModel. TODO? add some covariates in this very simple model.

Parameters:
namestr

The model’s name.

**kwargs
Model hyperparameters:

  • with_random_slope_age : bool (default True).

See also

LMEFitAlgorithm
LMEPersonalizeAlgorithm
Attributes:
namestr

The model’s name.

is_initializedbool

True if the model is initialized, False otherwise.

with_random_slope_agebool (default True)

Has the LME a random slope for subject’s age? Otherwise it only has a random intercept per subject.

featureslist of str

List of the model features.

Warning

LME has only one feature.

dimensionint

The dimension of the model.

parametersdict
Contains the model parameters. In particular:
  • ages_meanfloat

    Mean of ages (for normalization).

  • ages_stdfloat

    Std-dev of ages (for normalization).

  • fe_paramsnp.ndarray of float

    Fixed effects.

  • cov_renp.ndarray

    Variance-covariance matrix of random-effects.

  • cov_re_unscaled_invnp.ndarray

    Inverse of unscaled (= divided by variance of noise) variance-covariance matrix of random-effects. This matrix is used for personalization to new subjects.

  • noise_stdfloat

    Std-dev of Gaussian noise.

  • bse_fe, bse_renp.ndarray of float

    Standard errors on fixed-effects and random-effects respectively (not used in Leaspy).

Methods

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

get_hyperparameters(*[, with_features, ...])

Get all model hyperparameters.

hyperparameters_ok()

Check all model hyperparameters are ok.

initialize(dataset[, method])

Initialize the model given a Dataset and an initialization method.

load_hyperparameters(hyperparameters, *[, ...])

Load model hyperparameters from a dict.

load_parameters(parameters, *[, list_converter])

Instantiate or update the model's parameters.

save(path, **kwargs)

Save Leaspy object as JSON model parameter file.

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
compute_individual_trajectory(timepoints, individual_parameters: dict)

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsarray-like of ages (not normalized)

Timepoints to compute individual trajectory at.

individual_parametersdict
Individual parameters:

  • random_intercept

  • random_slope_age (if with_random_slope_age == True)

Returns:
torch.Tensor of float

The individual trajectories. The shape of the tensor is (n_individuals == 1, n_tpts == len(timepoints), n_features == 1).

property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_hyperparameters(*, with_features=True, with_properties=True, default=None) → Dict[str, Any]

Get all model hyperparameters.

Parameters:
with_features, with_propertiesbool (default True)

Whether to include features and respectively all _properties (i.e. _dynamic_ hyperparameters) in the returned dictionary.

defaultAny

Default value is something is an hyperparameter is missing (should not!).

Returns:
:obj:`dict` { hyperparam_namestr -> hyperparam_valueAny }
hyperparameters_ok() → bool

Check all model hyperparameters are ok.

Returns:
bool
initialize(dataset: Dataset, method: str = 'default') → None

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

The dataset we want to initialize from.

methodstr

A custom method to initialize the model

load_hyperparameters(hyperparameters: Dict[str, Any], *, with_defaults: bool = False) → None

Load model hyperparameters from a dict.

Parameters:
hyperparametersdict [ str, Any]

Contains the model’s hyperparameters.

with_defaultsbool (default False)

If True, it also resets hyperparameters that are part of the model but not included in hyperparameters to their default value.

Raises:
LeaspyModelInputError

If inconsistent hyperparameters.

load_parameters(parameters, *, list_converter=<built-in function array>) → None

Instantiate or update the model’s parameters.

Parameters:
parametersdict

Contains the model’s parameters.

list_convertercallable

The function to convert list objects.

save(path: str, **kwargs) → None

Save Leaspy object as JSON model parameter file.

Default save method: it can be overwritten in child class but should be generic…

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for json.dump method.

validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class ModelFactory

Bases: object

Return the wanted model given its name.

Methods

model(name, **kwargs)

Return the model object corresponding to name arg with possible kwargs.
static model(name: str, **kwargs) → BaseModel

Return the model object corresponding to name arg with possible kwargs.

Check name type and value.

Parameters:
namestr

The model’s name.

**kwargs

Contains model’s hyper-parameters. Raise an error if the keyword is inappropriate for the given model’s name.

Returns:
BaseModel

A child class object of models.BaseModel class object determined by name.

Raises:
LeaspyModelInputError

If an incorrect model is requested.

See also

Leaspy
class MultivariateModel(name: str, **kwargs)

Bases: AbstractMultivariateModel

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

Parameters:
namestr

The name of the model.

**kwargs

Hyperparameters of the model (including noise_model)

Raises:
LeaspyModelInputError

  • If name is not one of allowed sub-type: ‘univariate_linear’ or ‘univariate_logistic’

  • If hyperparameters are inconsistent

Attributes:
dimension

The dimension of the model.

features
is_ordinal

Property to check if the model is of ordinal sub-type.

is_ordinal_ranking

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

noise_model
ordinal_infos

Property to return the ordinal info dictionary.

Methods

check_noise_model_compatibility(model)

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(...)

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data, ...)

Compute canonical loss, which depends on the noise model.

compute_individual_ages_from_biomarker_values(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters).

compute_individual_ages_from_biomarker_values_tensorized(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_ages_from_biomarker_values_tensorized_logistic(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_attachment_tensorized(...)

Compute attachment term (per subject).

compute_individual_tensorized(timepoints, ...)

Compute the individual trajectories.

compute_individual_tensorized_linear(...[, ...])

Compute the individual trajectories.

compute_individual_tensorized_logistic(...)

Compute the individual trajectories.

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

compute_jacobian_tensorized(timepoints, ...)

Compute the jacobian of the model w.r.t.

compute_jacobian_tensorized_linear(...[, ...])

Compute the jacobian of the model (linear) w.r.t.

compute_jacobian_tensorized_logistic(...[, ...])

Compute the jacobian of the model (logistic) w.r.t.

compute_mean_traj(timepoints, *[, ...])

Compute trajectory of the model with individual parameters being the group-average ones.

compute_model_sufficient_statistics(data, ...)

Compute the model's sufficient statistics.

compute_ordinal_model_sufficient_statistics(...)

Compute the sufficient statistics given realizations.

compute_ordinal_pdf_from_ordinal_sf(ordinal_sf)

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

compute_regularity_individual_parameters(...)

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

compute_regularity_individual_realization(...)

Compute regularity term for IndividualRealization.

compute_regularity_population_realization(...)

Compute regularity term for PopulationRealization.

compute_regularity_realization(realization)

Compute regularity term for a AbstractRealization instance.

compute_regularity_variable(value, mean, std, *)

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

compute_sufficient_statistics(data, realizations)

Compute sufficient statistics from realizations.

get_additional_ordinal_population_random_variable_information()

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information()

Return the information on individual random variables relative to the model.

get_individual_variable_names()

Get the names of the individual variables of the model.

get_ordinal_parameters_updates_from_sufficient_statistics(...)

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information()

Return the information on population random variables relative to the model.

get_population_variable_names()

Get the names of the population variables of the model.

initialize(dataset[, method])

Overloads base initialization of model (base method takes care of features consistency checks).

initialize_MCMC_toolbox()

Initialize the model's MCMC toolbox attribute.

load_hyperparameters(hyperparameters)

Updates all model hyperparameters from the provided hyperparameters.

load_parameters(parameters)

Updates all model parameters from the provided parameters.

move_to_device(device)

Move a model and its relevant attributes to the specified torch.device.

postprocess_model_estimation(estimation, *)

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

time_reparametrization(timepoints, xi, tau)

Tensorized time reparametrization formula.

to_dict(*[, with_mixing_matrix])

Export Leaspy object as dictionary ready for JSON saving.

update_MCMC_toolbox(vars_to_update, realizations)

Update the model's MCMC toolbox attribute with the provided vars_to_update.

update_model_parameters_burn_in(data, ...)

Update the model's parameters during the burn in phase.

update_model_parameters_normal(data, ...)

Stochastic sufficient statistics used to update the parameters of the model.

update_ordinal_population_random_variable_information(...)

Update (in-place) the provided variable information dictionary.

update_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
SUBTYPES_SUFFIXES = {'linear': '_linear', 'logistic': '_logistic', 'mixed_linear-logistic': '_mixed'}
check_noise_model_compatibility(model: BaseNoiseModel) → None

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(model_or_model_grad: Tensor) → Tensor

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type=None) → Tensor

Compute canonical loss, which depends on the noise model.

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_inddict

Contain the individual parameters.

attribute_typestr or None (default)

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
losstorch.Tensor

shape = * (depending on noise-model, always summed over individuals & visits)

compute_individual_ages_from_biomarker_values(value: float | List[float], individual_parameters: Dict[str, Any], feature: str | None = None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters).

Consistency checks are done in the main API layer.

Parameters:
valuescalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the biomarker value(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (1, n_values).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

compute_individual_ages_from_biomarker_values_tensorized(value: Tensor, individual_parameters: dict, feature: str) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_ages_from_biomarker_values_tensorized_logistic(value: Tensor, individual_parameters: dict, feature: str) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_attachment_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type: str | None = None) → Tensor

Compute attachment term (per subject).

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_indDictParamsTorch

Contain the individual parameters.

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
attachmenttorch.Tensor

Negative Log-likelihood, shape = (n_subjects,).

compute_individual_tensorized(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_tensorized_linear(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_tensorized_logistic(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_trajectory(timepoints, individual_parameters: Dict[str, Any], *, skip_ips_checks: bool = False) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

skip_ips_checksbool (default: False)

Flag to skip consistency/compatibility checks and tensorization of individual_parameters when it was done earlier (speed-up).

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s) Shape of tensor is (1, n_tpts, n_features).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

LeaspyIndividualParamsInputError

if invalid individual parameters.

compute_jacobian_tensorized(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_jacobian_tensorized_linear(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model (linear) w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_jacobian_tensorized_logistic(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model (logistic) w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_mean_traj(timepoints: Tensor, *, attribute_type: str | None = None) → Tensor

Compute trajectory of the model with individual parameters being the group-average ones.

TODO check dimensions of io?

Parameters:
timepointstorch.Tensor of shape (1, n_timepoints)
attribute_typestr or None

If a string, should be “MCMC”.

Returns:
torch.Tensor of shape (1, n_timepoints, dimension)

The group-average values at given timepoints.

compute_model_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute the model’s sufficient statistics.

Parameters:
dataDataset

The input dataset.

realizationsCollectionRealization

The realizations from which to compute the model’s sufficient statistics.

Returns:
DictParamsTorch

The computed sufficient statistics.

compute_ordinal_model_sufficient_statistics(realizations: CollectionRealization) → Dict[str, Tensor]

Compute the sufficient statistics given realizations.

static compute_ordinal_pdf_from_ordinal_sf(ordinal_sf: Tensor, dim_ordinal_levels: int = 3) → Tensor

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

Parameters:
ordinal_sftorch.FloatTensor

Survival function values : ordinal_sf[…, l] is the proba to be superior or equal to l+1 Dimensions are: * 0=individual * 1=visit * 2=feature * 3=ordinal_level [l=0..L-1] * [4=individual_parameter_dim_when_gradient]

dim_ordinal_levelsint, default = 3

The dimension of the tensor where the ordinal levels are.

Returns:
ordinal_pdftorch.FloatTensor (same shape as input, except for dimension 3 which has one more element)

ordinal_pdf[…, l] is the proba to be equal to l (l=0..L)

compute_regularity_individual_parameters(individual_parameters: Dict[str, Tensor], *, include_constant: bool = False) → Tuple[Dict[str, Tensor], Dict[str, Tensor]]

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

Parameters:
individual_parametersdict [ str, torch.Tensor ]

Individual parameters as a dict of tensors of shape (n_ind, n_dims_param).

include_constantbool, optional

Whether to include a constant term or not. Default=False.

Returns:
regularitydict [ param_name: str, torch.Tensor ]

Regularity of the patient(s) corresponding to the given individual parameters. Tensors have shape (n_individuals).

regularity_gradsdict [ param_name: str, torch.Tensor ]

Gradient of regularity term with respect to individual parameters. Tensors have shape (n_individuals, n_dims_param).

compute_regularity_individual_realization(realization: IndividualRealization) → Tensor

Compute regularity term for IndividualRealization.

Parameters:
realizationIndividualRealization
Returns:
torch.Tensor of the same shape as IndividualRealization.tensor
compute_regularity_population_realization(realization: PopulationRealization) → Tensor

Compute regularity term for PopulationRealization.

Parameters:
realizationPopulationRealization
Returns:
torch.Tensor of the same shape as PopulationRealization.tensor
compute_regularity_realization(realization: AbstractRealization) → Tensor

Compute regularity term for a AbstractRealization instance.

Parameters:
realizationAbstractRealization
Returns:
torch.Tensor of the same shape as AbstractRealization.tensor
compute_regularity_variable(value: Tensor, mean: Tensor, std: Tensor, *, include_constant: bool = True, with_gradient: bool = False) → Tensor | Tuple[Tensor, Tensor]

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

Note

TODO: should be encapsulated in a RandomVariableSpecification class together with other specs of RV.

Parameters:
value, mean, stdtorch.Tensor of same shapes
include_constantbool (default True)

Whether we include or not additional terms constant with respect to value.

with_gradientbool (default False)

Whether we also return the gradient of regularity term with respect to value.

Returns:
torch.Tensor of same shape than input
compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from realizations.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor]
property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_additional_ordinal_population_random_variable_information() → Dict[str, Any]

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information() → Dict[str, Any]

Return the information on individual random variables relative to the model.

Returns:
DictParams

The information on the individual random variables.

get_individual_variable_names() → List[str]

Get the names of the individual variables of the model.

Returns:
list of str
get_ordinal_parameters_updates_from_sufficient_statistics(sufficient_statistics: Dict[str, Tensor]) → Dict[str, Tensor]

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information() → Dict[str, Any]

Return the information on population random variables relative to the model.

Returns:
DictParams

The information on the population random variables.

get_population_variable_names() → List[str]

Get the names of the population variables of the model.

Returns:
list of str
initialize(dataset: Dataset, method: str = 'default') → None

Overloads base initialization of model (base method takes care of features consistency checks).

Parameters:
datasetDataset

Input Dataset from which to initialize the model.

methodstr, optional

The initialization method to be used. Default=’default’.

initialize_MCMC_toolbox() → None

Initialize the model’s MCMC toolbox attribute.

property is_ordinal: bool

Property to check if the model is of ordinal sub-type.

property is_ordinal_ranking: bool

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

load_hyperparameters(hyperparameters: Dict[str, Any]) → None

Updates all model hyperparameters from the provided hyperparameters.

Parameters:
hyperparametersKwargsType

The hyperparameters to be loaded.

load_parameters(parameters: Dict[str, Any]) → None

Updates all model parameters from the provided parameters.

Parameters:
parametersKwargsType

The parameters to be loaded.

move_to_device(device: device) → None

Move a model and its relevant attributes to the specified torch.device.

Parameters:
devicetorch.device
property noise_model: BaseNoiseModel
property ordinal_infos: dict | None

Property to return the ordinal info dictionary.

postprocess_model_estimation(estimation: ndarray, *, ordinal_method: str = 'MLE', **kws) → ndarray | Dict[Hashable, ndarray]

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

Parameters:
estimationnumpy.ndarray[float]

The raw estimated values by model (from compute_individual_trajectory)

ordinal_methodstr

<!> Only used for ordinal models. * ‘MLE’ or ‘maximum_likelihood’ returns maximum likelihood estimator for each point (int) * ‘E’ or ‘expectation’ returns expectation (float) * ‘P’ or ‘probabilities’ returns probabilities of all-possible levels for a given feature:

{feature_name: array[float]<0..max_level_ft>}

**kws

Some extra keywords arguments that may be handled in the future.

Returns:
numpy.ndarray[float] or dict[str, numpy.ndarray[float]]

Post-processed values. In case using ‘probabilities’ mode, the values are a dictionary with keys being: (feature_name: str, feature_level: int<0..max_level_for_feature>) Otherwise it is a standard numpy.ndarray corresponding to different model features (in order)

save(path: str, **kwargs) → None

Save Leaspy object as json model parameter file.

TODO move logic upstream?

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for AbstractModel.to_dict() child method and json.dump function (default to indent=2).

static time_reparametrization(timepoints: Tensor, xi: Tensor, tau: Tensor) → Tensor

Tensorized time reparametrization formula.

Warning

Shapes of tensors must be compatible between them.

Parameters:
timepointstorch.Tensor

Timepoints to reparametrize.

xitorch.Tensor

Log-acceleration of individual(s).

tautorch.Tensor

Time-shift(s).

Returns:
torch.Tensor of same shape as timepoints
to_dict(*, with_mixing_matrix: bool = True) → Dict[str, Any]

Export Leaspy object as dictionary ready for JSON saving.

Parameters:
with_mixing_matrixbool (default True)

Save the mixing matrix in the exported file in its ‘parameters’ section.

Warning

It is not a real parameter and its value will be overwritten at model loading (orthonormal basis is recomputed from other “true” parameters and mixing matrix is then deduced from this orthonormal basis and the betas)! It was integrated historically because it is used for convenience in browser webtool and only there…

Returns:
KwargsType

The object as a dictionary.

update_MCMC_toolbox(vars_to_update: set, realizations: CollectionRealization) → None

Update the model’s MCMC toolbox attribute with the provided vars_to_update.

Parameters:
vars_to_updateset of str

The set of variable names to be updated.

realizationsCollectionRealization

The realizations to use for updating the MCMC toolbox.

update_model_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update the model’s parameters during the burn in phase.

During the burn-in phase, we only need to store the following parameters (cf. !66 and #60)

We don’t need to update the model “attributes” (never used during burn-in!).

Parameters:
dataDataset

The input dataset.

sufficient_statisticsDictParamsTorch

The sufficient statistics to use for parameter update.

update_model_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Stochastic sufficient statistics used to update the parameters of the model.

Note

TODOs:

  • factorize update_model_parameters_*** methods?

  • add a true, configurable, validation for all parameters? (e.g.: bounds on tau_var/std but also on tau_mean, …)

  • check the SS, especially the issue with mean(xi) and v_k

  • Learn the mean of xi and v_k

  • Set the mean of xi to 0 and add it to the mean of V_k

Parameters:
dataDataset

The input dataset.

sufficient_statisticsDictParamsTorch

The sufficient statistics to use for parameter update.

update_ordinal_population_random_variable_information(variables_info: Dict[str, Any]) → None

Update (in-place) the provided variable information dictionary.

Nota: this is needed due to different signification of v0 in ordinal model (common per-level velocity)

Parameters:
variables_infoDictParams

The variables information to be updated with ordinal logic.

update_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class MultivariateParallelModel(name: str, **kwargs)

Bases: AbstractMultivariateModel

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

Parameters:
namestr

The name of the model.

**kwargs

Hyperparameters of the model.

Attributes:
dimension

The dimension of the model.

features
is_ordinal

Property to check if the model is of ordinal sub-type.

is_ordinal_ranking

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

noise_model
ordinal_infos

Property to return the ordinal info dictionary.

Methods

check_noise_model_compatibility(model)

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(...)

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data, ...)

Compute canonical loss, which depends on the noise model.

compute_individual_ages_from_biomarker_values(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters).

compute_individual_ages_from_biomarker_values_tensorized(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_attachment_tensorized(...)

Compute attachment term (per subject).

compute_individual_tensorized(timepoints, ...)

Compute the individual trajectories.

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

compute_jacobian_tensorized(timepoints, ...)

Compute the jacobian of the model w.r.t.

compute_mean_traj(timepoints, *[, ...])

Compute trajectory of the model with individual parameters being the group-average ones.

compute_model_sufficient_statistics(data, ...)

Compute sufficient statistics from a CollectionRealization.

compute_ordinal_model_sufficient_statistics(...)

Compute the sufficient statistics given realizations.

compute_ordinal_pdf_from_ordinal_sf(ordinal_sf)

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

compute_regularity_individual_parameters(...)

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

compute_regularity_individual_realization(...)

Compute regularity term for IndividualRealization.

compute_regularity_population_realization(...)

Compute regularity term for PopulationRealization.

compute_regularity_realization(realization)

Compute regularity term for a AbstractRealization instance.

compute_regularity_variable(value, mean, std, *)

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

compute_sufficient_statistics(data, realizations)

Compute sufficient statistics from realizations.

get_additional_ordinal_population_random_variable_information()

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information()

Return the information on individual random variables relative to the model.

get_individual_variable_names()

Get the names of the individual variables of the model.

get_ordinal_parameters_updates_from_sufficient_statistics(...)

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information()

Return the information on population random variables relative to the model.

get_population_variable_names()

Get the names of the population variables of the model.

initialize(dataset[, method])

Overloads base initialization of model (base method takes care of features consistency checks).

initialize_MCMC_toolbox()

Initialize MCMC toolbox for calibration of model.

load_hyperparameters(hyperparameters)

Updates all model hyperparameters from the provided hyperparameters.

load_parameters(parameters)

Updates all model parameters from the provided parameters.

move_to_device(device)

Move a model and its relevant attributes to the specified torch.device.

postprocess_model_estimation(estimation, *)

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

time_reparametrization(timepoints, xi, tau)

Tensorized time reparametrization formula.

to_dict(*[, with_mixing_matrix])

Export Leaspy object as dictionary ready for JSON saving.

update_MCMC_toolbox(vars_to_update, realizations)

Update the MCMC toolbox with a CollectionRealization of model population parameters.

update_model_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_model_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

update_ordinal_population_random_variable_information(...)

Update (in-place) the provided variable information dictionary.

update_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
check_noise_model_compatibility(model: BaseNoiseModel) → None

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(model_or_model_grad: Tensor) → Tensor

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type=None) → Tensor

Compute canonical loss, which depends on the noise model.

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_inddict

Contain the individual parameters.

attribute_typestr or None (default)

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
losstorch.Tensor

shape = * (depending on noise-model, always summed over individuals & visits)

compute_individual_ages_from_biomarker_values(value: float | List[float], individual_parameters: Dict[str, Any], feature: str | None = None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters).

Consistency checks are done in the main API layer.

Parameters:
valuescalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the biomarker value(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (1, n_values).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

compute_individual_ages_from_biomarker_values_tensorized(value: Tensor, individual_parameters: dict, feature: str) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_attachment_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type: str | None = None) → Tensor

Compute attachment term (per subject).

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_indDictParamsTorch

Contain the individual parameters.

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
attachmenttorch.Tensor

Negative Log-likelihood, shape = (n_subjects,).

compute_individual_tensorized(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_trajectory(timepoints, individual_parameters: Dict[str, Any], *, skip_ips_checks: bool = False) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

skip_ips_checksbool (default: False)

Flag to skip consistency/compatibility checks and tensorization of individual_parameters when it was done earlier (speed-up).

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s) Shape of tensor is (1, n_tpts, n_features).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

LeaspyIndividualParamsInputError

if invalid individual parameters.

compute_jacobian_tensorized(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_mean_traj(timepoints: Tensor, *, attribute_type: str | None = None) → Tensor

Compute trajectory of the model with individual parameters being the group-average ones.

TODO check dimensions of io?

Parameters:
timepointstorch.Tensor of shape (1, n_timepoints)
attribute_typestr or None

If a string, should be “MCMC”.

Returns:
torch.Tensor of shape (1, n_timepoints, dimension)

The group-average values at given timepoints.

compute_model_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from a CollectionRealization.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor ]
compute_ordinal_model_sufficient_statistics(realizations: CollectionRealization) → Dict[str, Tensor]

Compute the sufficient statistics given realizations.

static compute_ordinal_pdf_from_ordinal_sf(ordinal_sf: Tensor, dim_ordinal_levels: int = 3) → Tensor

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

Parameters:
ordinal_sftorch.FloatTensor

Survival function values : ordinal_sf[…, l] is the proba to be superior or equal to l+1 Dimensions are: * 0=individual * 1=visit * 2=feature * 3=ordinal_level [l=0..L-1] * [4=individual_parameter_dim_when_gradient]

dim_ordinal_levelsint, default = 3

The dimension of the tensor where the ordinal levels are.

Returns:
ordinal_pdftorch.FloatTensor (same shape as input, except for dimension 3 which has one more element)

ordinal_pdf[…, l] is the proba to be equal to l (l=0..L)

compute_regularity_individual_parameters(individual_parameters: Dict[str, Tensor], *, include_constant: bool = False) → Tuple[Dict[str, Tensor], Dict[str, Tensor]]

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

Parameters:
individual_parametersdict [ str, torch.Tensor ]

Individual parameters as a dict of tensors of shape (n_ind, n_dims_param).

include_constantbool, optional

Whether to include a constant term or not. Default=False.

Returns:
regularitydict [ param_name: str, torch.Tensor ]

Regularity of the patient(s) corresponding to the given individual parameters. Tensors have shape (n_individuals).

regularity_gradsdict [ param_name: str, torch.Tensor ]

Gradient of regularity term with respect to individual parameters. Tensors have shape (n_individuals, n_dims_param).

compute_regularity_individual_realization(realization: IndividualRealization) → Tensor

Compute regularity term for IndividualRealization.

Parameters:
realizationIndividualRealization
Returns:
torch.Tensor of the same shape as IndividualRealization.tensor
compute_regularity_population_realization(realization: PopulationRealization) → Tensor

Compute regularity term for PopulationRealization.

Parameters:
realizationPopulationRealization
Returns:
torch.Tensor of the same shape as PopulationRealization.tensor
compute_regularity_realization(realization: AbstractRealization) → Tensor

Compute regularity term for a AbstractRealization instance.

Parameters:
realizationAbstractRealization
Returns:
torch.Tensor of the same shape as AbstractRealization.tensor
compute_regularity_variable(value: Tensor, mean: Tensor, std: Tensor, *, include_constant: bool = True, with_gradient: bool = False) → Tensor | Tuple[Tensor, Tensor]

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

Note

TODO: should be encapsulated in a RandomVariableSpecification class together with other specs of RV.

Parameters:
value, mean, stdtorch.Tensor of same shapes
include_constantbool (default True)

Whether we include or not additional terms constant with respect to value.

with_gradientbool (default False)

Whether we also return the gradient of regularity term with respect to value.

Returns:
torch.Tensor of same shape than input
compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from realizations.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor]
property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_additional_ordinal_population_random_variable_information() → Dict[str, Any]

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information() → Dict[str, Any]

Return the information on individual random variables relative to the model.

Returns:
DictParams

The information on the individual random variables.

get_individual_variable_names() → List[str]

Get the names of the individual variables of the model.

Returns:
list of str
get_ordinal_parameters_updates_from_sufficient_statistics(sufficient_statistics: Dict[str, Tensor]) → Dict[str, Tensor]

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information() → Dict[str, Any]

Return the information on population random variables relative to the model.

Returns:
DictParams

The information on the population random variables.

get_population_variable_names() → List[str]

Get the names of the population variables of the model.

Returns:
list of str
initialize(dataset: Dataset, method: str = 'default') → None

Overloads base initialization of model (base method takes care of features consistency checks).

Parameters:
datasetDataset

Input Dataset from which to initialize the model.

methodstr, optional

The initialization method to be used. Default=’default’.

initialize_MCMC_toolbox() → None

Initialize MCMC toolbox for calibration of model.

property is_ordinal: bool

Property to check if the model is of ordinal sub-type.

property is_ordinal_ranking: bool

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

load_hyperparameters(hyperparameters: Dict[str, Any]) → None

Updates all model hyperparameters from the provided hyperparameters.

Parameters:
hyperparametersKwargsType

The hyperparameters to be loaded.

load_parameters(parameters: Dict[str, Any]) → None

Updates all model parameters from the provided parameters.

Parameters:
parametersKwargsType

The parameters to be loaded.

move_to_device(device: device) → None

Move a model and its relevant attributes to the specified torch.device.

Parameters:
devicetorch.device
property noise_model: BaseNoiseModel
property ordinal_infos: dict | None

Property to return the ordinal info dictionary.

postprocess_model_estimation(estimation: ndarray, *, ordinal_method: str = 'MLE', **kws) → ndarray | Dict[Hashable, ndarray]

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

Parameters:
estimationnumpy.ndarray[float]

The raw estimated values by model (from compute_individual_trajectory)

ordinal_methodstr

<!> Only used for ordinal models. * ‘MLE’ or ‘maximum_likelihood’ returns maximum likelihood estimator for each point (int) * ‘E’ or ‘expectation’ returns expectation (float) * ‘P’ or ‘probabilities’ returns probabilities of all-possible levels for a given feature:

{feature_name: array[float]<0..max_level_ft>}

**kws

Some extra keywords arguments that may be handled in the future.

Returns:
numpy.ndarray[float] or dict[str, numpy.ndarray[float]]

Post-processed values. In case using ‘probabilities’ mode, the values are a dictionary with keys being: (feature_name: str, feature_level: int<0..max_level_for_feature>) Otherwise it is a standard numpy.ndarray corresponding to different model features (in order)

save(path: str, **kwargs) → None

Save Leaspy object as json model parameter file.

TODO move logic upstream?

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for AbstractModel.to_dict() child method and json.dump function (default to indent=2).

static time_reparametrization(timepoints: Tensor, xi: Tensor, tau: Tensor) → Tensor

Tensorized time reparametrization formula.

Warning

Shapes of tensors must be compatible between them.

Parameters:
timepointstorch.Tensor

Timepoints to reparametrize.

xitorch.Tensor

Log-acceleration of individual(s).

tautorch.Tensor

Time-shift(s).

Returns:
torch.Tensor of same shape as timepoints
to_dict(*, with_mixing_matrix: bool = True) → Dict[str, Any]

Export Leaspy object as dictionary ready for JSON saving.

Parameters:
with_mixing_matrixbool (default True)

Save the mixing matrix in the exported file in its ‘parameters’ section.

Warning

It is not a real parameter and its value will be overwritten at model loading (orthonormal basis is recomputed from other “true” parameters and mixing matrix is then deduced from this orthonormal basis and the betas)! It was integrated historically because it is used for convenience in browser webtool and only there…

Returns:
KwargsType

The object as a dictionary.

update_MCMC_toolbox(vars_to_update: set, realizations: CollectionRealization) → None

Update the MCMC toolbox with a CollectionRealization of model population parameters.

Parameters:
vars_to_updateset of str

Names of the population parameters to update in MCMC toolbox.

realizationsCollectionRealization

All the realizations to update MCMC toolbox with.

update_model_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_model_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_ordinal_population_random_variable_information(variables_info: Dict[str, Any]) → None

Update (in-place) the provided variable information dictionary.

Nota: this is needed due to different signification of v0 in ordinal model (common per-level velocity)

Parameters:
variables_infoDictParams

The variables information to be updated with ordinal logic.

update_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.

class UnivariateModel(name: str, **kwargs)

Bases: MultivariateModel

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

Parameters:
namestr

The name of the model.

**kwargs

Hyperparameters of the model.

Raises:
LeaspyModelInputError

  • If name is not one of allowed sub-type: ‘univariate_linear’ or ‘univariate_logistic’

  • If hyperparameters are inconsistent

Attributes:
dimension

The dimension of the model.

features
is_ordinal

Property to check if the model is of ordinal sub-type.

is_ordinal_ranking

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

noise_model
ordinal_infos

Property to return the ordinal info dictionary.

Methods

check_noise_model_compatibility(model)

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(...)

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data, ...)

Compute canonical loss, which depends on the noise model.

compute_individual_ages_from_biomarker_values(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters).

compute_individual_ages_from_biomarker_values_tensorized(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_ages_from_biomarker_values_tensorized_logistic(...)

For one individual, compute age(s) at which the given features values are reached (given the subject's individual parameters), with tensorized inputs.

compute_individual_attachment_tensorized(...)

Compute attachment term (per subject).

compute_individual_tensorized(timepoints, ...)

Compute the individual trajectories.

compute_individual_tensorized_linear(...[, ...])

Compute the individual trajectories.

compute_individual_tensorized_logistic(...)

Compute the individual trajectories.

compute_individual_trajectory(timepoints, ...)

Compute scores values at the given time-point(s) given a subject's individual parameters.

compute_jacobian_tensorized(timepoints, ...)

Compute the jacobian of the model w.r.t.

compute_jacobian_tensorized_linear(...[, ...])

Compute the jacobian of the model (linear) w.r.t.

compute_jacobian_tensorized_logistic(...[, ...])

Compute the jacobian of the model (logistic) w.r.t.

compute_mean_traj(timepoints, *[, ...])

Compute trajectory of the model with individual parameters being the group-average ones.

compute_model_sufficient_statistics(data, ...)

Compute the model's sufficient statistics.

compute_ordinal_model_sufficient_statistics(...)

Compute the sufficient statistics given realizations.

compute_ordinal_pdf_from_ordinal_sf(ordinal_sf)

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

compute_regularity_individual_parameters(...)

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

compute_regularity_individual_realization(...)

Compute regularity term for IndividualRealization.

compute_regularity_population_realization(...)

Compute regularity term for PopulationRealization.

compute_regularity_realization(realization)

Compute regularity term for a AbstractRealization instance.

compute_regularity_variable(value, mean, std, *)

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

compute_sufficient_statistics(data, realizations)

Compute sufficient statistics from realizations.

get_additional_ordinal_population_random_variable_information()

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information()

Return the information on individual random variables relative to the model.

get_individual_variable_names()

Get the names of the individual variables of the model.

get_ordinal_parameters_updates_from_sufficient_statistics(...)

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information()

Return the information on population random variables relative to the model.

get_population_variable_names()

Get the names of the population variables of the model.

initialize(dataset[, method])

Overloads base initialization of model (base method takes care of features consistency checks).

initialize_MCMC_toolbox()

Initialize the model's MCMC toolbox attribute.

load_hyperparameters(hyperparameters)

Updates all model hyperparameters from the provided hyperparameters.

load_parameters(parameters)

Updates all model parameters from the provided parameters.

move_to_device(device)

Move a model and its relevant attributes to the specified torch.device.

postprocess_model_estimation(estimation, *)

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

save(path, **kwargs)

Save Leaspy object as json model parameter file.

time_reparametrization(timepoints, xi, tau)

Tensorized time reparametrization formula.

to_dict(*[, with_mixing_matrix])

Export Leaspy object as dictionary ready for JSON saving.

update_MCMC_toolbox(vars_to_update, realizations)

Update the model's MCMC toolbox attribute with the provided vars_to_update.

update_model_parameters_burn_in(data, ...)

Update the model's parameters during the burn in phase.

update_model_parameters_normal(data, ...)

Stochastic sufficient statistics used to update the parameters of the model.

update_ordinal_population_random_variable_information(...)

Update (in-place) the provided variable information dictionary.

update_parameters_burn_in(data, ...)

Update model parameters (burn-in phase).

update_parameters_normal(data, ...)

Update model parameters (after burn-in phase).

validate_compatibility_of_dataset(dataset)

Raise if the given Dataset is not compatible with the current model.
SUBTYPES_SUFFIXES = {'univariate_linear': '_linear', 'univariate_logistic': '_logistic'}
attributes: AbstractManifoldModelAttributes
check_noise_model_compatibility(model: BaseNoiseModel) → None

Check compatibility between the model instance and provided noise model.

compute_appropriate_ordinal_model(model_or_model_grad: Tensor) → Tensor

Post-process model values (or their gradient) if needed.

compute_canonical_loss_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type=None) → Tensor

Compute canonical loss, which depends on the noise model.

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_inddict

Contain the individual parameters.

attribute_typestr or None (default)

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
losstorch.Tensor

shape = * (depending on noise-model, always summed over individuals & visits)

compute_individual_ages_from_biomarker_values(value: float | List[float], individual_parameters: Dict[str, Any], feature: str | None = None) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters).

Consistency checks are done in the main API layer.

Parameters:
valuescalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the biomarker value(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (1, n_values).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

compute_individual_ages_from_biomarker_values_tensorized(value: Tensor, individual_parameters: dict, feature: str) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_ages_from_biomarker_values_tensorized_logistic(value: Tensor, individual_parameters: dict, feature: str) → Tensor

For one individual, compute age(s) at which the given features values are reached (given the subject’s individual parameters), with tensorized inputs.

Parameters:
valuetorch.Tensor of shape (1, n_values)

Contains the biomarker value(s) of the subject.

individual_parametersDictParamsTorch

Contains the individual parameters. Each individual parameter should be a torch.Tensor.

featurestr (or None)

Name of the considered biomarker.

Note

Optional for UnivariateModel, compulsory for MultivariateModel.

Returns:
torch.Tensor

Contains the subject’s ages computed at the given values(s). Shape of tensor is (n_values, 1).

compute_individual_attachment_tensorized(data: Dataset, param_ind: Dict[str, Tensor], *, attribute_type: str | None = None) → Tensor

Compute attachment term (per subject).

Parameters:
dataDataset

Contains the data of the subjects, in particular the subjects’ time-points and the mask for nan values & padded visits.

param_indDictParamsTorch

Contain the individual parameters.

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
attachmenttorch.Tensor

Negative Log-likelihood, shape = (n_subjects,).

compute_individual_tensorized(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_tensorized_linear(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_tensorized_logistic(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Tensor

Compute the individual trajectories.

Parameters:
timepointstorch.Tensor

The time points for which to compute the trajectory.

individual_parametersDictParamsTorch

The individual parameters to use.

attribute_typeAny, optional
Returns:
torch.Tensor

Individual trajectories.

compute_individual_trajectory(timepoints, individual_parameters: Dict[str, Any], *, skip_ips_checks: bool = False) → Tensor

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:
timepointsscalar or array_like[scalar] (list, tuple, numpy.ndarray)

Contains the age(s) of the subject.

individual_parametersdict

Contains the individual parameters. Each individual parameter should be a scalar or array_like.

skip_ips_checksbool (default: False)

Flag to skip consistency/compatibility checks and tensorization of individual_parameters when it was done earlier (speed-up).

Returns:
torch.Tensor

Contains the subject’s scores computed at the given age(s) Shape of tensor is (1, n_tpts, n_features).

Raises:
LeaspyModelInputError

If computation is tried on more than 1 individual.

LeaspyIndividualParamsInputError

if invalid individual parameters.

compute_jacobian_tensorized(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_jacobian_tensorized_linear(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model (linear) w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_jacobian_tensorized_logistic(timepoints: Tensor, individual_parameters: dict, *, attribute_type=None) → Dict[str, Tensor]

Compute the jacobian of the model (logistic) w.r.t. each individual parameter.

This function aims to be used in ScipyMinimize to speed up optimization.

Note

As most of numerical operations are repeated when computing model & jacobian, we should create a single method that is able to compute model & jacobian “together” (= efficiently) when requested with a flag for instance.

Parameters:
timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_dims_param).

attribute_typestr or None

Flag to ask for MCMC attributes instead of model’s attributes.

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

compute_mean_traj(timepoints: Tensor, *, attribute_type: str | None = None) → Tensor

Compute trajectory of the model with individual parameters being the group-average ones.

TODO check dimensions of io?

Parameters:
timepointstorch.Tensor of shape (1, n_timepoints)
attribute_typestr or None

If a string, should be “MCMC”.

Returns:
torch.Tensor of shape (1, n_timepoints, dimension)

The group-average values at given timepoints.

compute_model_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute the model’s sufficient statistics.

Parameters:
dataDataset

The input dataset.

realizationsCollectionRealization

The realizations from which to compute the model’s sufficient statistics.

Returns:
DictParamsTorch

The computed sufficient statistics.

compute_ordinal_model_sufficient_statistics(realizations: CollectionRealization) → Dict[str, Tensor]

Compute the sufficient statistics given realizations.

static compute_ordinal_pdf_from_ordinal_sf(ordinal_sf: Tensor, dim_ordinal_levels: int = 3) → Tensor

Computes the probability density (or its jacobian) of an ordinal model [P(X = l), l=0..L] from ordinal_sf which are the survival function probabilities [P(X > l), i.e. P(X >= l+1), l=0..L-1] (or its jacobian).

Parameters:
ordinal_sftorch.FloatTensor

Survival function values : ordinal_sf[…, l] is the proba to be superior or equal to l+1 Dimensions are: * 0=individual * 1=visit * 2=feature * 3=ordinal_level [l=0..L-1] * [4=individual_parameter_dim_when_gradient]

dim_ordinal_levelsint, default = 3

The dimension of the tensor where the ordinal levels are.

Returns:
ordinal_pdftorch.FloatTensor (same shape as input, except for dimension 3 which has one more element)

ordinal_pdf[…, l] is the proba to be equal to l (l=0..L)

compute_regularity_individual_parameters(individual_parameters: Dict[str, Tensor], *, include_constant: bool = False) → Tuple[Dict[str, Tensor], Dict[str, Tensor]]

Compute the regularity terms (and their gradients if requested), per individual variable of the model.

Parameters:
individual_parametersdict [ str, torch.Tensor ]

Individual parameters as a dict of tensors of shape (n_ind, n_dims_param).

include_constantbool, optional

Whether to include a constant term or not. Default=False.

Returns:
regularitydict [ param_name: str, torch.Tensor ]

Regularity of the patient(s) corresponding to the given individual parameters. Tensors have shape (n_individuals).

regularity_gradsdict [ param_name: str, torch.Tensor ]

Gradient of regularity term with respect to individual parameters. Tensors have shape (n_individuals, n_dims_param).

compute_regularity_individual_realization(realization: IndividualRealization) → Tensor

Compute regularity term for IndividualRealization.

Parameters:
realizationIndividualRealization
Returns:
torch.Tensor of the same shape as IndividualRealization.tensor
compute_regularity_population_realization(realization: PopulationRealization) → Tensor

Compute regularity term for PopulationRealization.

Parameters:
realizationPopulationRealization
Returns:
torch.Tensor of the same shape as PopulationRealization.tensor
compute_regularity_realization(realization: AbstractRealization) → Tensor

Compute regularity term for a AbstractRealization instance.

Parameters:
realizationAbstractRealization
Returns:
torch.Tensor of the same shape as AbstractRealization.tensor
compute_regularity_variable(value: Tensor, mean: Tensor, std: Tensor, *, include_constant: bool = True, with_gradient: bool = False) → Tensor | Tuple[Tensor, Tensor]

Compute regularity term (Gaussian distribution) and optionally its gradient wrt value.

Note

TODO: should be encapsulated in a RandomVariableSpecification class together with other specs of RV.

Parameters:
value, mean, stdtorch.Tensor of same shapes
include_constantbool (default True)

Whether we include or not additional terms constant with respect to value.

with_gradientbool (default False)

Whether we also return the gradient of regularity term with respect to value.

Returns:
torch.Tensor of same shape than input
compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → Dict[str, Tensor]

Compute sufficient statistics from realizations.

Parameters:
dataDataset
realizationsCollectionRealization
Returns:
dict [ suff_stat: str, torch.Tensor]
property dimension: int | None

The dimension of the model. If the private attribute is defined, then it takes precedence over the feature length. The associated setters are responsible for their coherence.

property features: List[str] | None
get_additional_ordinal_population_random_variable_information() → Dict[str, Any]

Return the information of additional population random variables for the ordinal model.

get_individual_random_variable_information() → Dict[str, Any]

Return the information on individual random variables relative to the model.

Returns:
DictParams

The information on the individual random variables.

get_individual_variable_names() → List[str]

Get the names of the individual variables of the model.

Returns:
list of str
get_ordinal_parameters_updates_from_sufficient_statistics(sufficient_statistics: Dict[str, Tensor]) → Dict[str, Tensor]

Return a dictionary computed from provided sufficient statistics for updating the parameters.

get_population_random_variable_information() → Dict[str, Any]

Return the information on population random variables relative to the model.

Returns:
DictParams

The information on the population random variables.

get_population_variable_names() → List[str]

Get the names of the population variables of the model.

Returns:
list of str
initialize(dataset: Dataset, method: str = 'default') → None

Overloads base initialization of model (base method takes care of features consistency checks).

Parameters:
datasetDataset

Input Dataset from which to initialize the model.

methodstr, optional

The initialization method to be used. Default=’default’.

initialize_MCMC_toolbox() → None

Initialize the model’s MCMC toolbox attribute.

is_initialized: bool
property is_ordinal: bool

Property to check if the model is of ordinal sub-type.

property is_ordinal_ranking: bool

Property to check if the model is of ordinal-ranking sub-type (working with survival functions).

load_hyperparameters(hyperparameters: Dict[str, Any]) → None

Updates all model hyperparameters from the provided hyperparameters.

Parameters:
hyperparametersKwargsType

The hyperparameters to be loaded.

load_parameters(parameters: Dict[str, Any]) → None

Updates all model parameters from the provided parameters.

Parameters:
parametersKwargsType

The parameters to be loaded.

move_to_device(device: device) → None

Move a model and its relevant attributes to the specified torch.device.

Parameters:
devicetorch.device
property noise_model: BaseNoiseModel
property ordinal_infos: dict | None

Property to return the ordinal info dictionary.

parameters: KwargsType | None
postprocess_model_estimation(estimation: ndarray, *, ordinal_method: str = 'MLE', **kws) → ndarray | Dict[Hashable, ndarray]

Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.

Parameters:
estimationnumpy.ndarray[float]

The raw estimated values by model (from compute_individual_trajectory)

ordinal_methodstr

<!> Only used for ordinal models. * ‘MLE’ or ‘maximum_likelihood’ returns maximum likelihood estimator for each point (int) * ‘E’ or ‘expectation’ returns expectation (float) * ‘P’ or ‘probabilities’ returns probabilities of all-possible levels for a given feature:

{feature_name: array[float]<0..max_level_ft>}

**kws

Some extra keywords arguments that may be handled in the future.

Returns:
numpy.ndarray[float] or dict[str, numpy.ndarray[float]]

Post-processed values. In case using ‘probabilities’ mode, the values are a dictionary with keys being: (feature_name: str, feature_level: int<0..max_level_for_feature>) Otherwise it is a standard numpy.ndarray corresponding to different model features (in order)

save(path: str, **kwargs) → None

Save Leaspy object as json model parameter file.

TODO move logic upstream?

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for AbstractModel.to_dict() child method and json.dump function (default to indent=2).

source_dimension: int
static time_reparametrization(timepoints: Tensor, xi: Tensor, tau: Tensor) → Tensor

Tensorized time reparametrization formula.

Warning

Shapes of tensors must be compatible between them.

Parameters:
timepointstorch.Tensor

Timepoints to reparametrize.

xitorch.Tensor

Log-acceleration of individual(s).

tautorch.Tensor

Time-shift(s).

Returns:
torch.Tensor of same shape as timepoints
to_dict(*, with_mixing_matrix: bool = True) → Dict[str, Any]

Export Leaspy object as dictionary ready for JSON saving.

Parameters:
with_mixing_matrixbool (default True)

Save the mixing matrix in the exported file in its ‘parameters’ section.

Warning

It is not a real parameter and its value will be overwritten at model loading (orthonormal basis is recomputed from other “true” parameters and mixing matrix is then deduced from this orthonormal basis and the betas)! It was integrated historically because it is used for convenience in browser webtool and only there…

Returns:
KwargsType

The object as a dictionary.

update_MCMC_toolbox(vars_to_update: set, realizations: CollectionRealization) → None

Update the model’s MCMC toolbox attribute with the provided vars_to_update.

Parameters:
vars_to_updateset of str

The set of variable names to be updated.

realizationsCollectionRealization

The realizations to use for updating the MCMC toolbox.

update_model_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update the model’s parameters during the burn in phase.

During the burn-in phase, we only need to store the following parameters (cf. !66 and #60)

We don’t need to update the model “attributes” (never used during burn-in!).

Parameters:
dataDataset

The input dataset.

sufficient_statisticsDictParamsTorch

The sufficient statistics to use for parameter update.

update_model_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Stochastic sufficient statistics used to update the parameters of the model.

Note

TODOs:

  • factorize update_model_parameters_*** methods?

  • add a true, configurable, validation for all parameters? (e.g.: bounds on tau_var/std but also on tau_mean, …)

  • check the SS, especially the issue with mean(xi) and v_k

  • Learn the mean of xi and v_k

  • Set the mean of xi to 0 and add it to the mean of V_k

Parameters:
dataDataset

The input dataset.

sufficient_statisticsDictParamsTorch

The sufficient statistics to use for parameter update.

update_ordinal_population_random_variable_information(variables_info: Dict[str, Any]) → None

Update (in-place) the provided variable information dictionary.

Nota: this is needed due to different signification of v0 in ordinal model (common per-level velocity)

Parameters:
variables_infoDictParams

The variables information to be updated with ordinal logic.

update_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
update_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) → None

Update model parameters (after burn-in phase).

Parameters:
dataDataset
sufficient_statisticsdict [ suff_stat: str, torch.Tensor ]
validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:
datasetDataset

The Dataset we want to model.

Raises:
LeaspyModelInputError

  • If the Dataset has a number of dimensions smaller than 2.

  • If the Dataset does not have the same dimensionality as the model.

  • If the Dataset’s headers do not match the model’s.