leaspy.models.abstract_model module
- class AbstractModel(name: str, **kwargs)
Bases:
ABC
Contains the common attributes & methods of the different models.
- Parameters
- namestr
The name of the model
- **kwargs
Hyperparameters for the model
- Attributes
- is_initializedbool
Indicates if the model is initialized
- namestr
The model’s name
- featureslist[str]
Names of the model features
- parametersdict
Contains the model’s parameters
- noise_modelstr
The noise structure for the model. cf.
NoiseModel
to see possible values.- regularization_distribution_factoryfunction dist params ->
torch.distributions.Distribution
Factory of torch distribution to compute log-likelihoods for regularization (gaussian by default) (Not used anymore)
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_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 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.
Information on model's random variables.
save
(path, **kwargs)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_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: FloatTensor, individual_parameters: Dict[str, FloatTensor], *, 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_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]
- abstract 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
- dataset
Dataset
The dataset we want to initialize from.
- methodstr
A custom method to initialize the model
- dataset
- 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
- 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 device.
- Parameters
- devicetorch.device
- 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
- abstract save(path: str, **kwargs) None
Save Leaspy object as json model parameter file.
- Parameters
- pathstr
Path to store the model’s parameters.
- **kwargs
Keyword arguments for json.dump method.
- 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_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