leaspy.models.mcmc_saem_compatible

Classes

McmcSaemCompatibleModel

Defines probabilistic models compatible with an MCMC SAEM estimation.

Module Contents

class McmcSaemCompatibleModel(name, *, obs_models, fit_metrics=None, **kwargs)

Bases: leaspy.models.base.BaseModel

Defines probabilistic models compatible with an MCMC SAEM estimation.

Parameters:
namestr

The name of the model.

obs_modelsObservationModel or Iterable[ObservationModel]

The noise model for observations (keyword-only parameter).

fit_metricsdict

Metrics that should be measured during the fit of the model and reported back to the user.

**kwargs

Hyperparameters for the model

Attributes:
is_initializedbool

Indicates if the model is initialized.

namestr

The model’s name.

featureslist of str

Names of the model features.

parametersdict

Contains the model’s parameters

obs_modelsTuple[ObservationModel, …]

The observation model(s) associated to the model.

fit_metricsdict

Contains the metrics that are measured during the fit of the model and reported to the user.

_stateState

Private instance holding all values for model variables and their derived variables.

Parameters:
obs_models
fit_metrics = None
tracked_variables: set[str]
track_variable(variable)
Parameters:

variable (leaspy.variables.specs.VariableName)

Return type:

None

track_variables(variables)
Parameters:

variables (Iterable[leaspy.variables.specs.VariableName])

Return type:

None

untrack_variable(variable)
Parameters:

variable (leaspy.variables.specs.VariableName)

Return type:

None

untrack_variables(variables)
Parameters:

variables (Iterable[leaspy.variables.specs.VariableName])

Return type:

None

property observation_model_names: list[str]
Return type:

list[str]

property state: State
Return type:

State

property dag: VariablesDAG
Return type:

VariablesDAG

property hyperparameters_names: tuple[leaspy.variables.specs.VariableName, Ellipsis]
Return type:

tuple[leaspy.variables.specs.VariableName, Ellipsis]

property parameters_names: tuple[leaspy.variables.specs.VariableName, Ellipsis]
Return type:

tuple[leaspy.variables.specs.VariableName, Ellipsis]

property population_variables_names: tuple[leaspy.variables.specs.VariableName, Ellipsis]
Return type:

tuple[leaspy.variables.specs.VariableName, Ellipsis]

property individual_variables_names: tuple[leaspy.variables.specs.VariableName, Ellipsis]
Return type:

tuple[leaspy.variables.specs.VariableName, Ellipsis]

property parameters: leaspy.utils.typing.DictParamsTorch

Dictionary of values for model parameters.

Return type:

leaspy.utils.typing.DictParamsTorch

property hyperparameters: leaspy.utils.typing.DictParamsTorch

Dictionary of values for model hyperparameters.

Return type:

leaspy.utils.typing.DictParamsTorch

has_observation_model_with_name(name)
Parameters:

name (str)

Return type:

bool

abstractmethod to_dict()

Export model as a dictionary ready for export.

Returns:
KwargsType

The model instance serialized as a dictionary.

Return type:

leaspy.utils.typing.KwargsType

save(path, **kwargs)

Save Leaspy object as json model parameter file.

TODO move logic upstream?

Parameters:
pathstr

Path to store the model’s parameters.

**kwargs

Keyword arguments for AbstractModel.to_dict() child method and json.dump function (default to indent=2).

Parameters:

path (str)

Return type:

None

load_parameters(parameters)

Instantiate or update the model’s parameters.

It assumes that all model hyperparameters are defined.

Parameters:
parametersdict [ str, Any ]

Contains the model’s parameters.

Parameters:

parameters (leaspy.utils.typing.KwargsType)

Return type:

None

compute_individual_trajectory(timepoints, individual_parameters, *, skip_ips_checks=False)

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

Note

The model uses its current internal state.

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.

Parameters:

  • individual_parameters (leaspy.utils.typing.DictParams)

  • skip_ips_checks (bool)

Return type:

Tensor

compute_prior_trajectory(timepoints, prior_type, *, n_individuals=None)

Compute trajectory of the model for prior mode or mean of individual parameters.

Parameters:
timepointstorch.Tensor [1, n_timepoints]
prior_typeLatentVariableInitType
n_individualsint, optional

The number of individuals.

Returns:
torch.Tensor [1, n_timepoints, dimension]

The group-average values at given timepoints.

Parameters:
Return type:

leaspy.utils.weighted_tensor.TensorOrWeightedTensor[float]

compute_mean_traj(timepoints)

Trajectory for average of individual parameters (not really meaningful for non-linear models).

Parameters:

timepoints (Tensor)

compute_mode_traj(timepoints)

Most typical individual trajectory.

Parameters:

timepoints (Tensor)

abstractmethod compute_jacobian_tensorized(state)

Compute the jacobian of the model w.r.t. each individual parameter, given the input state.

This function aims to be used in ScipyMinimize to speed up optimization.

Parameters:
stateState

Instance holding values for all model variables (including latent individual variables), as well as: - timepoints : torch.Tensor of shape (n_individuals, n_timepoints)

Returns:
dict [ param_name: str, torch.Tensor ]

Tensors are of shape (n_individuals, n_timepoints, n_features, n_dims_param).

Parameters:

state (State)

Return type:

leaspy.utils.typing.DictParamsTorch

classmethod compute_sufficient_statistics(state)

Compute sufficient statistics from state.

Parameters:
stateState
Returns:
dict [ suff_stat: str, torch.Tensor]
Parameters:

state (State)

Return type:

leaspy.variables.specs.SuffStatsRW

classmethod update_parameters(state, sufficient_statistics, *, burn_in)

Update model parameters of the provided state.

Parameters:
stateState
sufficient_statisticsdict[suff_stat: str, torch.Tensor]
burn_inbool
Parameters:

  • state (State)

  • sufficient_statistics (leaspy.variables.specs.SuffStatsRO)

  • burn_in (bool)

Return type:

None

get_variables_specs()

Return the specifications of the variables (latent variables, derived variables, model ‘parameters’) that are part of the model.

Returns:
NamedVariables

The specifications of the model’s variables.

Return type:

NamedVariables

initialize(dataset=None, method=None)

Overloads base model initialization (in particular to handle internal model State).

<!> We do not put data variables in internal model state at this stage (done in algorithm)

Parameters:
datasetDataset, optional

Input dataset from which to initialize the model.

methodInitializationMethod, optional

The initialization method to be used. Default=’default’.

Parameters:
Return type:

None

abstractmethod put_individual_parameters(state, dataset)
Parameters:
put_data_variables(state, dataset)

Put all the needed data variables inside the provided state (in-place).

Parameters:
Return type:

None

reset_data_variables(state)

Reset all data variables inside the provided state (in-place).

Parameters:

state (State)

Return type:

None

move_to_device(device)

Move a model and its relevant attributes to the specified torch.device.

Parameters:
devicetorch.device
Parameters:

device (device)

Return type:

None