leaspy.models.multivariate_model module

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

Bases: AbstractMultivariateModel

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

Parameters

namestr: 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

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

Methods

`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 values at timepoints according to the model.
`compute_individual_tensorized_linear`(...[, ...])	Compute the individual values at timepoints according to the model (linear).
`compute_individual_tensorized_logistic`(...)	Compute the individual values at timepoints according to the model (logistic).
`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_ordinal_pdf_from_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_ordinal_sf_from_ordinal_pdf`(ordinal_pdf)	Compute the ordinal survival function values [P(X > l), i.e. P(X >= l+1), l=0..L-1] (l=0..L-1) from the ordinal probability density [P(X = l), l=0..L] (assuming ordinal levels are in last dimension).
`compute_regularity_realization`(realization)	Compute regularity term for a `Realization` instance.
`compute_regularity_variable`(value, mean, std, *)	Compute regularity term (Gaussian distribution), low-level.
`compute_sufficient_statistics`(data, realizations)	Compute sufficient statistics from realizations
`compute_sum_squared_per_ft_tensorized`(...[, ...])	Compute the square of the residuals per subject per feature
`compute_sum_squared_tensorized`(dataset, ...)	Compute the square of the residuals per subject
`get_individual_realization_names`()	Get names of individual variables of the model.
`get_param_from_real`(realizations)	Get individual parameters realizations from all model realizations
`get_population_realization_names`()	Get names of population variables of the model.
`initialize`(dataset[, method])	Initialize the model given a dataset and an initialization method.
`initialize_MCMC_toolbox`()	Initialize Monte-Carlo Markov-Chain toolbox for calibration of model
`initialize_realizations_for_model`(...)	Initialize a `CollectionRealization` used during model fitting or mode/mean realization personalization.
`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 device.
`postprocess_model_estimation`(estimation, *)	Extra layer of processing used to output nice estimated values in main API Leaspy.estimate.
`random_variable_informations`()	Information on model's random variables.
`save`(path[, with_mixing_matrix])	Save Leaspy object as json model parameter file.
`smart_initialization_realizations`(dataset, ...)	Smart initialization of realizations if needed (input may be modified in-place).
`time_reparametrization`(timepoints, xi, tau)	Tensorized time reparametrization formula
`update_MCMC_toolbox`(vars_to_update, realizations)	Update the MCMC toolbox with a collection of realizations of model population parameters.
`update_model_parameters_burn_in`(data, ...)	Update model parameters (burn-in phase)
`update_model_parameters_normal`(data, suff_stats)	Update model parameters (after burn-in phase)

SUBTYPES_SUFFIXES = {'linear': '_linear', 'logistic': '_logistic', 'mixed_linear-logistic': '_mixed'}

compute_individual_ages_from_biomarker_values(value: Union[float, List[float]], individual_parameters: Dict[str, Any], feature: Optional[str] = None)

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 (optional for univariate models, compulsory for multivariate models).

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

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_parametersdict: Contains the individual parameters. Each individual parameter should be a torch.Tensor
featurestr (or None): Name of the considered biomarker (optional for univariate models, compulsory for multivariate models).

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

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_parametersdict: Contains the individual parameters. Each individual parameter should be a torch.Tensor
featurestr (or None): Name of the considered biomarker (optional for univariate models, compulsory for multivariate models).

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: DictParamsTorch, *, attribute_type) → torch.FloatTensor

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_inddict: Contain the individual parameters
attribute_typeAny: Flag to ask for MCMC attributes instead of model’s attributes.

Returns

attachmenttorch.Tensor: Negative Log-likelihood, shape = (n_subjects,)

Raises

LeaspyModelInputError: If invalid noise_model for model

compute_individual_tensorized(timepoints, individual_parameters, *, attribute_type=None)

Compute the individual values at timepoints according to the model.

Parameters

timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict[param_name: str, torch.Tensor of shape (n_individuals, n_dims_param)]
attribute_typeAny (default 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_tensorized_linear(timepoints, individual_parameters, *, attribute_type=None)

Compute the individual values at timepoints according to the model (linear).

Parameters

timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict[param_name: str, torch.Tensor of shape (n_individuals, n_dims_param)]
attribute_typeAny (default 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_tensorized_logistic(timepoints, individual_parameters, *, attribute_type=None)

Compute the individual values at timepoints according to the model (logistic).

Parameters

timepointstorch.Tensor of shape (n_individuals, n_timepoints)
individual_parametersdict[param_name: str, torch.Tensor of shape (n_individuals, n_dims_param)]
attribute_typeAny (default 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)

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, individual_parameters, *, attribute_type=None)

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

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

TODO: 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 of shape (n_individuals, n_dims_param)]
attribute_typeAny (default None): Flag to ask for MCMC attributes instead of model’s attributes.

Returns

dict[param_name: str, torch.Tensor of shape (n_individuals, n_timepoints, n_features, n_dims_param)]

compute_jacobian_tensorized_linear(timepoints, individual_parameters, *, attribute_type=None)

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.

TODO: 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 of shape (n_individuals, n_dims_param)]
attribute_typeAny (default None): Flag to ask for MCMC attributes instead of model’s attributes.

Returns

dict[param_name: str, torch.Tensor of shape (n_individuals, n_timepoints, n_features, n_dims_param)]

compute_jacobian_tensorized_logistic(timepoints, individual_parameters, *, attribute_type=None)

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.

TODO: 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 of shape (n_individuals, n_dims_param)]
attribute_typeAny (default None): Flag to ask for MCMC attributes instead of model’s attributes.

Returns

dict[param_name: str, torch.Tensor of shape (n_individuals, n_timepoints, n_features, n_dims_param)]

compute_mean_traj(timepoints, *, attribute_type: Optional[str] = None)

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

TODO check dimensions of io?

Parameters

timepointstorch.Tensor [1, n_timepoints]
attribute_type‘MCMC’ or None

Returns

torch.Tensor [1, n_timepoints, dimension]: The group-average values at given timepoints

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)

static compute_ordinal_sf_from_ordinal_pdf(ordinal_pdf: Union[Tensor, ndarray]): Compute the ordinal survival function values [P(X > l), i.e. P(X >= l+1), l=0..L-1] (l=0..L-1) from the ordinal probability density [P(X = l), l=0..L] (assuming ordinal levels are in last dimension).

compute_regularity_realization(realization: Realization)

Compute regularity term for a Realization instance.

Parameters

realizationRealization

Returns

torch.Tensor of the same shape as realization.tensor_realizations

compute_regularity_variable(value: FloatTensor, mean: FloatTensor, std: FloatTensor, *, include_constant: bool = True) → FloatTensor

Compute regularity term (Gaussian distribution), low-level.

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.

Returns

torch.Tensor of same shape than input

compute_sufficient_statistics(data, realizations)

Compute sufficient statistics from realizations

Parameters

dataDataset
realizationsCollectionRealization

Returns

dict[suff_stat: str, torch.Tensor]

compute_sum_squared_per_ft_tensorized(dataset: Dataset, param_ind: DictParamsTorch, *, attribute_type=None) → torch.FloatTensor

Compute the square of the residuals per subject per feature

Parameters

datasetDataset: Contains the data of the subjects, in particular the subjects’ time-points and the mask (?)
param_inddict: Contain the individual parameters
attribute_typeAny (default None): Flag to ask for MCMC attributes instead of model’s attributes.

Returns

torch.Tensor of shape (n_individuals,dimension): Contains L2 residual for each subject and each feature

compute_sum_squared_tensorized(dataset: Dataset, param_ind: DictParamsTorch, *, attribute_type=None) → torch.FloatTensor

Compute the square of the residuals per subject

Parameters

datasetDataset: Contains the data of the subjects, in particular the subjects’ time-points and the mask (?)
param_inddict: Contain the individual parameters
attribute_typeAny (default None): Flag to ask for MCMC attributes instead of model’s attributes.

Returns

torch.Tensor of shape (n_individuals,): Contains L2 residual for each subject

get_individual_realization_names() → List[str]

Get names of individual variables of the model.

Returns

list[str]

get_param_from_real(realizations: CollectionRealization) → Dict[str, FloatTensor]

Get individual parameters realizations from all model realizations

<!> The tensors are not cloned and so a link continue to exist between the individual parameters: and the underlying tensors of realizations.

Parameters

realizationsCollectionRealization

Returns

dict[param_name: str, torch.Tensor [n_individuals, dims_param]]: Individual parameters

get_population_realization_names() → List[str]

Get names of population variables of the model.

Returns

list[str]

initialize(dataset, method: str = 'default')

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

initialize_MCMC_toolbox(): Initialize Monte-Carlo Markov-Chain toolbox for calibration of model

initialize_realizations_for_model(n_individuals: int, **init_kws) → CollectionRealization

Initialize a CollectionRealization used during model fitting or mode/mean realization personalization.

Parameters

n_individualsint: Number of individuals to track
**init_kws: Keyword arguments passed to CollectionRealization.initialize(). (In particular individual_variable_init_at_mean to “initialize at mean” or skip_variable to filter some variables)

Returns

CollectionRealization

property is_ordinal: bool: Property to check if the model is of ordinal sub-type.

load_hyperparameters(hyperparameters: Dict[str, Any])

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

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

Parameters

devicetorch.device

postprocess_model_estimation(estimation: ndarray, *, ordinal_method: str = 'MLE', **kws) → Union[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)

random_variable_informations()

Information on model’s random variables.

Returns

dict[str, Any]

name: str
Name of the random variable
type: ‘population’ or ‘individual’
Individual or population random variable?
shape: tuple[int, …]
Shape of the variable (only 1D for individual and 1D or 2D for pop. are supported)
rv_type: str
An indication (not used in code) on the probability distribution used for the var (only Gaussian is supported)
scale: optional float
The fixed scale to use for initial std-dev in the corresponding sampler. When not defined, sampler will rely on scales estimated at model initialization. cf. GibbsSampler

save(path: str, with_mixing_matrix: bool = True, **kwargs)

Save Leaspy object as json model parameter file.

Parameters

pathstr: Path to store the model’s parameters.
with_mixing_matrixbool (default True): Save the mixing matrix in the exported file in its ‘parameters’ section. <!> 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…
**kwargs: Keyword arguments for json.dump method. Default to: dict(indent=2)

smart_initialization_realizations(dataset: Dataset, realizations: CollectionRealization) → CollectionRealization

Smart initialization of realizations if needed (input may be modified in-place).

Default behavior to return realizations as they are (no smart trick).

Parameters

datasetDataset
realizationsCollectionRealization

Returns

CollectionRealization

static time_reparametrization(timepoints: FloatTensor, xi: FloatTensor, tau: FloatTensor) → FloatTensor

Tensorized time reparametrization formula

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

update_MCMC_toolbox(vars_to_update, realizations)

Update the MCMC toolbox with a collection of realizations of model population parameters.

Parameters

vars_to_updatecontainer[str] (list, tuple, …): 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, realizations)

Update model parameters (burn-in phase)

Parameters

dataDataset
realizationsCollectionRealization

update_model_parameters_normal(data, suff_stats)

Update model parameters (after burn-in phase)

Parameters

dataDataset
suff_statsdict[suff_stat: str, torch.Tensor]