`leaspy.models`.MultivariateModel

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.

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.

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

noise_std
*_mean/std for regularization of individual variables
others population parameters for regularization of population variables

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.

leaspy.models.MultivariateModel

`leaspy.models`.MultivariateModel