leaspy.models.abstract_multivariate_model
.AbstractMultivariateModel
- 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
- Raises
LeaspyModelInputError
if inconsistent hyperparameters
- Attributes
is_ordinal
Property to check if the model is of ordinal sub-type.
Methods
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 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_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 names of individual variables of the model.
get_param_from_real
(realizations)Get individual parameters realizations from all model realizations
Get names of population variables of the model.
initialize
(dataset[, method])Initialize the model given a dataset and an initialization method.
Initialize Monte-Carlo Markov-Chain toolbox for calibration of 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.
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)
- 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).
- valuescalar or array_like[scalar] (list, tuple,
- 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: FloatTensor, individual_parameters: Dict[str, FloatTensor], feature: Optional[str]) FloatTensor
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
- data
Dataset
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.
- data
- Returns
- attachment
torch.Tensor
Negative Log-likelihood, shape = (n_subjects,)
- attachment
- Raises
LeaspyModelInputError
If invalid noise_model for model
- abstract compute_individual_tensorized(timepoints, individual_parameters, *, attribute_type=None) FloatTensor
Compute the individual values at timepoints according to the model.
- Parameters
- timepoints
torch.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.
- timepoints
- 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)
- timepointsscalar or array_like[scalar] (list, tuple,
- 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: FloatTensor, individual_parameters: Dict[str, FloatTensor], *, attribute_type=None) FloatTensor
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
- timepoints
torch.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.
- timepoints
- Returns
- dict[param_name: str,
torch.Tensor
of shape (n_individuals, n_timepoints, n_features, n_dims_param)]
- dict[param_name: str,
- 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
- timepoints
torch.Tensor
[1, n_timepoints] - attribute_type‘MCMC’ or None
- timepoints
- 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
- realization
Realization
- realization
- 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, std
torch.Tensor
of same shapes - include_constantbool (default True)
Whether we include or not additional terms constant with respect to value.
- value, mean, std
- Returns
torch.Tensor
of same shape than input
- abstract compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) DictParamsTorch
Compute sufficient statistics from realizations
- Parameters
- data
Dataset
- realizations
CollectionRealization
- data
- Returns
- dict[suff_stat: str,
torch.Tensor
]
- dict[suff_stat: str,
- 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
- dataset
Dataset
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.
- dataset
- 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
- dataset
Dataset
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.
- dataset
- 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
- realizations
CollectionRealization
- realizations
- Returns
- dict[param_name: str,
torch.Tensor
[n_individuals, dims_param]] Individual parameters
- dict[param_name: str,
- 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
- dataset
Dataset
The dataset we want to initialize from.
- methodstr
A custom method to initialize the model
- dataset
- abstract initialize_MCMC_toolbox() None
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
- 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: 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 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)
- abstract random_variable_informations() Dict[str, Any]
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
- dataset
Dataset
- realizations
CollectionRealization
- dataset
- Returns
- static time_reparametrization(timepoints: FloatTensor, xi: FloatTensor, tau: FloatTensor) FloatTensor
Tensorized time reparametrization formula
<!> Shapes of tensors must be compatible between them.
- Parameters
- timepoints
torch.Tensor
Timepoints to reparametrize
- xi
torch.Tensor
Log-acceleration of individual(s)
- tau
torch.Tensor
Time-shift(s)
- timepoints
- Returns
torch.Tensor
of same shape as timepoints
- abstract update_MCMC_toolbox(vars_to_update: List[str], realizations) None
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
- realizations
CollectionRealization
All the realizations to update MCMC toolbox with
- abstract update_model_parameters_burn_in(data: Dataset, realizations: CollectionRealization) None
Update model parameters (burn-in phase)
- Parameters
- data
Dataset
- realizations
CollectionRealization
- data
- abstract update_model_parameters_normal(data: Dataset, suff_stats: DictParamsTorch) None
Update model parameters (after burn-in phase)
- Parameters
- data
Dataset
- suff_statsdict[suff_stat: str,
torch.Tensor
]
- data