leaspy.models.abstract_multivariate_model module
- class AbstractMultivariateModel(name: str, **kwargs)
Bases:
OrdinalModelMixin
,AbstractModel
Contains the common attributes & methods of the multivariate models.
- Parameters:
- name
str
Name of the model.
- **kwargs
Hyperparameters for the model (including noise_model).
- name
- 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 compatibility between the model instance and provided noise model.
Post-process model values (or their gradient) if needed.
compute_canonical_loss_tensorized
(data, ...)Compute canonical loss, which depends on the noise model.
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 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 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 the regularity terms (and their gradients if requested), per individual variable of the model.
Compute regularity term for
IndividualRealization
.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.
Return the information on individual random variables relative to the model.
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.
Return the information on population random variables relative to the model.
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 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 (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:
- Returns:
- loss
torch.Tensor
shape = * (depending on noise-model, always summed over individuals & visits)
- loss
- 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_parameters
dict
Contains the individual parameters. Each individual parameter should be a scalar or array_like.
- feature
str
(or None) Name of the considered biomarker.
Note
Optional for
UnivariateModel
, compulsory forMultivariateModel
.
- valuescalar or array_like[scalar] (
- 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:
- value
torch.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
.- feature
str
(or None) Name of the considered biomarker.
Note
Optional for
UnivariateModel
, compulsory forMultivariateModel
.
- value
- 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:
- Returns:
- attachment
torch.Tensor
Negative Log-likelihood, shape =
(n_subjects,)
.
- attachment
- abstract compute_individual_tensorized(timepoints: Tensor, individual_parameters: Dict[str, Tensor], *, attribute_type=None) Tensor
Compute the individual trajectories.
- Parameters:
- timepoints
torch.Tensor
The time points for which to compute the trajectory.
- individual_parametersDictParamsTorch
The individual parameters to use.
- attribute_typeAny, optional
- timepoints
- 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_parameters
dict
Contains the individual parameters. Each individual parameter should be a scalar or array_like.
- skip_ips_checks
bool
(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] (
- 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:
- timepoints
torch.Tensor
of shape(n_individuals, n_timepoints)
- individual_parameters
dict
[ param_name:str
,torch.Tensor
] Tensors are of shape
(n_individuals, n_dims_param)
.- attribute_type
str
or None Flag to ask for MCMC attributes instead of model’s attributes.
- timepoints
- 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:
- timepoints
torch.Tensor
of shape(1, n_timepoints)
- attribute_type
str
or None If a string, should be “MCMC”.
- timepoints
- 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:
- data
Dataset
- realizations
CollectionRealization
- data
- 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_parameters
dict
[str
,torch.Tensor
] Individual parameters as a dict of tensors of shape
(n_ind, n_dims_param)
.- include_constant
bool
, optional Whether to include a constant term or not. Default=False.
- individual_parameters
- Returns:
- regularity
dict
[ param_name:str
,torch.Tensor
] Regularity of the patient(s) corresponding to the given individual parameters. Tensors have shape
(n_individuals)
.- regularity_grads
dict
[ param_name:str
,torch.Tensor
] Gradient of regularity term with respect to individual parameters. Tensors have shape
(n_individuals, n_dims_param)
.
- regularity
- compute_regularity_individual_realization(realization: IndividualRealization) Tensor
Compute regularity term for
IndividualRealization
.- Parameters:
- realization
IndividualRealization
- realization
- Returns:
torch.Tensor
of the same shape asIndividualRealization.tensor
- compute_regularity_population_realization(realization: PopulationRealization) Tensor
Compute regularity term for
PopulationRealization
.- Parameters:
- realization
PopulationRealization
- realization
- Returns:
torch.Tensor
of the same shape asPopulationRealization.tensor
- compute_regularity_realization(realization: AbstractRealization) Tensor
Compute regularity term for a
AbstractRealization
instance.- Parameters:
- realization
AbstractRealization
- realization
- Returns:
torch.Tensor
of the same shape asAbstractRealization.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, std
torch.Tensor
of same shapes - include_constant
bool
(defaultTrue
) Whether we include or not additional terms constant with respect to value.
- with_gradient
bool
(defaultFalse
) Whether we also return the gradient of regularity term with respect to value.
- value, mean, std
- Returns:
torch.Tensor
of same shape than input
- compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) Dict[str, Tensor]
Compute sufficient statistics from realizations.
- Parameters:
- data
Dataset
- realizations
CollectionRealization
- data
- 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.
- 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_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.
- initialize(dataset: Dataset, method: str = 'default') None
Overloads base initialization of model (base method takes care of features consistency checks).
- 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:
- device
torch.device
- device
- property noise_model: BaseNoiseModel
- 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:
- path
str
Path to store the model’s parameters.
- **kwargs
Keyword arguments for
AbstractModel.to_dict()
child method andjson.dump
function (default to indent=2).
- path
- static time_reparametrization(timepoints: Tensor, xi: Tensor, tau: Tensor) Tensor
Tensorized time reparametrization formula.
Warning
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
- to_dict(*, with_mixing_matrix: bool = True) Dict[str, Any]
Export
Leaspy
object as dictionary ready for JSON saving.- Parameters:
- with_mixing_matrix
bool
(defaultTrue
) 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…
- with_mixing_matrix
- 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_update
set
ofstr
Names of the population parameters to update in MCMC toolbox.
- realizations
CollectionRealization
All the realizations to update MCMC toolbox with.
- vars_to_update
- abstract update_model_parameters_burn_in(data: Dataset, sufficient_statistics: Dict[str, Tensor]) None
Update model parameters (burn-in phase).
- Parameters:
- data
Dataset
- sufficient_statistics
dict
[ suff_stat:str
,torch.Tensor
]
- data
- abstract update_model_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) None
Update model parameters (after burn-in phase).
- Parameters:
- data
Dataset
- sufficient_statistics
dict
[ suff_stat:str
,torch.Tensor
]
- data
- 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:
- data
Dataset
- sufficient_statistics
dict
[ suff_stat:str
,torch.Tensor
]
- data
- update_parameters_normal(data: Dataset, sufficient_statistics: Dict[str, Tensor]) None
Update model parameters (after burn-in phase).
- Parameters:
- data
Dataset
- sufficient_statistics
dict
[ suff_stat:str
,torch.Tensor
]
- data