leaspy.models.univariate_model module
- class UnivariateModel(name: str, **kwargs)
Bases:
AbstractModel
,OrdinalModelMixin
Univariate (logistic or linear) model for a single variable of interest.
- 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
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 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 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 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, **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_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 = {'univariate_linear': '_linear', 'univariate_logistic': '_logistic'}
- 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
- 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
- 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
- compute_individual_tensorized(timepoints, individual_parameters, *, attribute_type=None)
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_tensorized_linear(timepoints, individual_parameters, *, attribute_type=None)
Compute the individual values at timepoints according to the model (linear).
- 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_tensorized_logistic(timepoints, individual_parameters, *, attribute_type=None)
Compute the individual values at timepoints according to the model (logistic).
- 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
- 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
- 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_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
- 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_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
- 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? TODO generalize in abstract manifold model
- 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
- compute_sufficient_statistics(data, realizations)
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='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
- 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
- load_hyperparameters(hyperparameters: dict)
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, **kwargs)
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
- update_MCMC_toolbox(vars_to_update, realizations)
Update the MCMC toolbox with a collection of realizations of model population parameters.
TODO to move in the MCMC-fit algorithm
- 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
- update_model_parameters_burn_in(data, realizations)
Update model parameters (burn-in phase)
- Parameters
- data
Dataset
- realizations
CollectionRealization
- data
- update_model_parameters_normal(data, suff_stats)
Update model parameters (after burn-in phase)
- Parameters
- data
Dataset
- suff_statsdict[suff_stat: str,
torch.Tensor
]
- data