leaspy.models.lme module

class LMEModel(name: str, **kwargs)

Bases: GenericModel

LMEModel is a benchmark model that fits and personalize a linear mixed-effects model.

The model specification is the following:

with:

• : value of the feature of the i-th subject at his j-th visit,

• : age of the i-th subject at his j-th visit.

• : residual Gaussian noise (independent between visits)

Warning

This model must be fitted on one feature only (univariate model).

TODO? should inherit from AbstractModel. TODO? add some covariates in this very simple model.

Parameters:

namestr

The model’s name.

**kwargs

Model hyperparameters:

• with_random_slope_age : bool (default True).

See also

LMEFitAlgorithm

LMEPersonalizeAlgorithm

Attributes:

namestr

The model’s name.

is_initializedbool

True if the model is initialized, False otherwise.

with_random_slope_agebool (default True)

Has the LME a random slope for subject’s age? Otherwise it only has a random intercept per subject.

featureslist of str

List of the model features.

Warning

LME has only one feature.

dimensionint

The dimension of the model.

parametersdict

Contains the model parameters. In particular:

• ages_meanfloat

  Mean of ages (for normalization).

• ages_stdfloat

  Std-dev of ages (for normalization).

• fe_paramsnp.ndarray of float

  Fixed effects.

• cov_renp.ndarray

  Variance-covariance matrix of random-effects.

• cov_re_unscaled_invnp.ndarray

  Inverse of unscaled (= divided by variance of noise) variance-covariance matrix of random-effects. This matrix is used for personalization to new subjects.

• noise_stdfloat

  Std-dev of Gaussian noise.

• bse_fe, bse_renp.ndarray of float

  Standard errors on fixed-effects and random-effects respectively (not used in Leaspy).

Methods

compute_individual_trajectory(timepoints, ...)	Compute scores values at the given time-point(s) given a subject's individual parameters.
get_hyperparameters(*[, with_features, ...])	Get all model hyperparameters.
hyperparameters_ok()	Check all model hyperparameters are ok.
initialize(dataset[, method])	Initialize the model given a Dataset and an initialization method.
load_hyperparameters(hyperparameters, *[, ...])	Load model hyperparameters from a dict.
load_parameters(parameters, *[, list_converter])	Instantiate or update the model's parameters.
save(path, **kwargs)	Save Leaspy object as JSON model parameter file.
validate_compatibility_of_dataset(dataset)	Raise if the given Dataset is not compatible with the current model.

compute_individual_trajectory(timepoints, individual_parameters: dict)

Compute scores values at the given time-point(s) given a subject’s individual parameters.

Parameters:

timepointsarray-like of ages (not normalized)

Timepoints to compute individual trajectory at.

individual_parametersdict

Individual parameters:

• random_intercept

• random_slope_age (if with_random_slope_age == True)

Returns:

torch.Tensor of float

The individual trajectories. The shape of the tensor is (n_individuals == 1, n_tpts == len(timepoints), n_features == 1).

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.

property features: List[str] | None

get_hyperparameters(*, with_features=True, with_properties=True, default=None) → Dict[str, Any]

Get all model hyperparameters.

Parameters:

with_features, with_propertiesbool (default True)

Whether to include features and respectively all _properties (i.e. _dynamic_ hyperparameters) in the returned dictionary.

defaultAny

Default value is something is an hyperparameter is missing (should not!).

Returns:

:obj:`dict` { hyperparam_namestr -> hyperparam_valueAny }

hyperparameters_ok() → bool

Check all model hyperparameters are ok.

Returns:

bool

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

load_hyperparameters(hyperparameters: Dict[str, Any], *, with_defaults: bool = False) → None

Load model hyperparameters from a dict.

Parameters:

hyperparametersdict [ str, Any]

Contains the model’s hyperparameters.

with_defaultsbool (default False)

If True, it also resets hyperparameters that are part of the model but not included in hyperparameters to their default value.

Raises:

LeaspyModelInputError

If inconsistent hyperparameters.

load_parameters(parameters, *, list_converter=<built-in function array>) → None

Instantiate or update the model’s parameters.

Parameters:

parametersdict

Contains the model’s parameters.

list_convertercallable

The function to convert list objects.

save(path: str, **kwargs) → None

Save Leaspy object as JSON model parameter file.

Default save method: it can be overwritten in child class but should be generic…

Parameters:

pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for json.dump method.

validate_compatibility_of_dataset(dataset: Dataset) → None

Raise if the given Dataset is not compatible with the current model.

Parameters:

datasetDataset

The Dataset we want to model.

Raises:

LeaspyModelInputError

• If the Dataset has a number of dimensions smaller than 2.

• If the Dataset does not have the same dimensionality as the model.

• If the Dataset’s headers do not match the model’s.