`leaspy.models.abstract_model`.AbstractModel

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

`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_attachment_tensorized`(...)	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_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_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.
`random_variable_informations`()	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).

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

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

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

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

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

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

abstract compute_sufficient_statistics(data: Dataset, realizations: CollectionRealization) → DictParamsTorch

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]

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

datasetDataset: The dataset we want to initialize from.
methodstr: A custom method to initialize the 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

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

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

abstract update_model_parameters_burn_in(data: Dataset, realizations: CollectionRealization) → None

Update model parameters (burn-in phase)

Parameters

dataDataset
realizationsCollectionRealization

abstract update_model_parameters_normal(data: Dataset, suff_stats: DictParamsTorch) → None

Update model parameters (after burn-in phase)

Parameters

dataDataset
suff_statsdict[suff_stat: str, torch.Tensor]

leaspy.models.abstract_model.AbstractModel

`leaspy.models.abstract_model`.AbstractModel