leaspy.samplers package

Submodules

Module contents

class AbstractIndividualSampler(name: str, shape: Tuple[int, ...], *, n_patients: int, acceptation_history_length: int = 25)

Bases: AbstractSampler

Abstract class for samplers of individual random variables.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
n_patientsint: Number of patients.
acceptation_history_lengthint > 0 (default 25): Deepness (= number of iterations) of the history kept for computing the mean acceptation rate. (It is the same for population or individual variables.)

Attributes:

namestr: Name of variable
shapetuple of int: Shape of variable
n_patientsint: Number of patients.
acceptation_history_lengthint: Deepness (= number of iterations) of the history kept for computing the mean acceptation rate. (It is the same for population or individual variables.)
acceptation_historytorch.Tensor: History of binary acceptations to compute mean acceptation rate for the sampler in MCMC-SAEM algorithm. It keeps the history of the last acceptation_history_length steps.

Methods

sample(dataset, model, realizations, ...)

Sample new realization (either population or individual) for a given CollectionRealization state, Dataset, AbstractModel, and temperature.

abstract sample(dataset: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

Sample new realization (either population or individual) for a given CollectionRealization state, Dataset, AbstractModel, and temperature.

<!> Modifies in-place the realizations object, <!> as well as the model through its update_MCMC_toolbox for population variables.

Parameters:

datasetDataset: Dataset class object build with leaspy class object Data, model & algo
modelAbstractModel: Model for loss computations and updates
realizationsCollectionRealization: Contain the current state & information of all the variables of interest
temperature_invfloat > 0: Inverse of the temperature used in tempered MCMC-SAEM
**attachment_computation_kws: Optional keyword arguments for attachment computations. As of now, we only use it for individual variables, and only attribute_type. It is used to know whether to compute attachments from the MCMC toolbox (esp. during fit) or to compute it from regular model parameters (esp. during personalization in mean/mode realization)

Returns:

attachment, regularity_vartorch.Tensor: The attachment and regularity tensors (only for the current variable) at the end of this sampling step (globally or per individual, depending on variable type). The tensors are 0D for population variables, or 1D for individual variables (with length n_individuals).

abstract property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

class AbstractPopulationSampler(name: str, shape: Tuple[int, ...], *, acceptation_history_length: int = 25, mask: Tensor | None = None)

Bases: AbstractSampler

Abstract class for samplers of population random variables.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
acceptation_history_lengthint > 0 (default 25): Deepness (= number of iterations) of the history kept for computing the mean acceptation rate. (It is the same for population or individual variables.)
masktorch.Tensor, optional: If not None, mask should be 0/1 tensor indicating the sampling variable to adapt variance from 1 indices are kept for sampling while 0 are excluded.

Attributes:

namestr: Name of variable
shapetuple of int: Shape of variable
acceptation_history_lengthint: Deepness (= number of iterations) of the history kept for computing the mean acceptation rate. (It is the same for population or individual variables.)
acceptation_historytorch.Tensor: History of binary acceptations to compute mean acceptation rate for the sampler in MCMC-SAEM algorithm. It keeps the history of the last acceptation_history_length steps.
masktorch.Tensor of obj:bool, optional: If not None, mask should be 0/1 tensor indicating the sampling variable to adapt variance from 1 (True) indices are kept for sampling while 0 (False) are excluded.

Methods

sample(dataset, model, realizations, ...)

Sample new realization (either population or individual) for a given CollectionRealization state, Dataset, AbstractModel, and temperature.

abstract sample(dataset: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

Sample new realization (either population or individual) for a given CollectionRealization state, Dataset, AbstractModel, and temperature.

<!> Modifies in-place the realizations object, <!> as well as the model through its update_MCMC_toolbox for population variables.

Parameters:

datasetDataset: Dataset class object build with leaspy class object Data, model & algo
modelAbstractModel: Model for loss computations and updates
realizationsCollectionRealization: Contain the current state & information of all the variables of interest
temperature_invfloat > 0: Inverse of the temperature used in tempered MCMC-SAEM
**attachment_computation_kws: Optional keyword arguments for attachment computations. As of now, we only use it for individual variables, and only attribute_type. It is used to know whether to compute attachments from the MCMC toolbox (esp. during fit) or to compute it from regular model parameters (esp. during personalization in mean/mode realization)

Returns:

attachment, regularity_vartorch.Tensor: The attachment and regularity tensors (only for the current variable) at the end of this sampling step (globally or per individual, depending on variable type). The tensors are 0D for population variables, or 1D for individual variables (with length n_individuals).

abstract property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

class AbstractSampler(name: str, shape: Tuple[int, ...], *, acceptation_history_length: int = 25)

Bases: ABC

Abstract sampler class.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
acceptation_history_lengthint > 0 (default 25): Deepness (= number of iterations) of the history kept for computing the mean acceptation rate. (It is the same for population or individual variables.)

Raises:

LeaspyModelInputError

Attributes:

namestr: Name of variable
shapetuple of int: Shape of variable
acceptation_history_lengthint: Deepness (= number of iterations) of the history kept for computing the mean acceptation rate. (Same for population or individual variables by default.)
acceptation_historytorch.Tensor: History of binary acceptations to compute mean acceptation rate for the sampler in MCMC-SAEM algorithm. It keeps the history of the last acceptation_history_length steps.

Methods

sample(dataset, model, realizations, ...)

Sample new realization (either population or individual) for a given CollectionRealization state, Dataset, AbstractModel, and temperature.

abstract sample(dataset: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

Sample new realization (either population or individual) for a given CollectionRealization state, Dataset, AbstractModel, and temperature.

<!> Modifies in-place the realizations object, <!> as well as the model through its update_MCMC_toolbox for population variables.

Parameters:

datasetDataset: Dataset class object build with leaspy class object Data, model & algo
modelAbstractModel: Model for loss computations and updates
realizationsCollectionRealization: Contain the current state & information of all the variables of interest
temperature_invfloat > 0: Inverse of the temperature used in tempered MCMC-SAEM
**attachment_computation_kws: Optional keyword arguments for attachment computations. As of now, we only use it for individual variables, and only attribute_type. It is used to know whether to compute attachments from the MCMC toolbox (esp. during fit) or to compute it from regular model parameters (esp. during personalization in mean/mode realization)

Returns:

attachment, regularity_vartorch.Tensor: The attachment and regularity tensors (only for the current variable) at the end of this sampling step (globally or per individual, depending on variable type). The tensors are 0D for population variables, or 1D for individual variables (with length n_individuals).

abstract property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

class IndividualGibbsSampler(name: str, shape: tuple, *, n_patients: int, scale: float | FloatTensor, random_order_dimension: bool = True, mean_acceptation_rate_target_bounds: Tuple[float, float] = (0.2, 0.4), adaptive_std_factor: float = 0.1, **base_sampler_kws)

Bases: GibbsSamplerMixin, AbstractIndividualSampler

Gibbs sampler for individual variables.

Individual variables are handled with a grouped Gibbs sampler. There is currently no other sampler available for individual variables.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
n_patientsint: Number of patients.
scalefloat > 0 or torch.FloatTensor > 0: An approximate scale for the variable. It will be used to scale the initial adaptive std-dev used in sampler. An extra 1% factor will be applied on top of this scale (STD_SCALE_FACTOR) Note that if you pass a torch tensor, its shape should be compatible with shape of the variable.
random_order_dimensionbool (default True): This parameter controls whether we randomize the order of indices during the sampling loop. Article https://proceedings.neurips.cc/paper/2016/hash/e4da3b7fbbce2345d7772b0674a318d5-Abstract.html gives a rationale on why we should activate this flag.
mean_acceptation_rate_target_bounds:obj:`tuple`[lower_bound: float, upper_bound: float] with 0 < lower_bound < upper_bound < 1: Bounds on mean acceptation rate. Outside this range, the adaptation of the std-dev of sampler is triggered so to maintain a target acceptation rate in between these too bounds (e.g: ~30%).
adaptive_std_factorfloat in ]0, 1[: Factor by which we increase or decrease the std-dev of sampler when we are out of the custom bounds for the mean acceptation rate. We decrease it by 1 - factor if too low, and increase it with 1 + factor if too high.
**base_sampler_kws: Keyword arguments passed to AbstractSampler init method. In particular, you may pass the acceptation_history_length hyperparameter.

Attributes:

shape_acceptation
shape_adapted_std: Shape of adaptative variance.

Methods

`sample`(data, model, realizations, ...)	For each individual variable, compute current patient-batched attachment and regularity.
`validate_scale`(scale)	Validate user provided scale in `float` or `torch.Tensor` form.

STD_SCALE_FACTOR: ClassVar[float] = 0.5

sample(data: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

For each individual variable, compute current patient-batched attachment and regularity.

Propose a new value for the individual variable, and compute new patient-batched attachment and regularity.

Do a MH step, keeping if better, or if worse with a probability.

Parameters:

dataDataset
modelAbstractModel
realizationsCollectionRealization
temperature_invfloat > 0
**attachment_computation_kws: Optional keyword arguments for attachment computations. As of now, we only use it for individual variables, and only attribute_type. It is used to know whether to compute attachments from the MCMC toolbox (esp. during fit) or to compute it from regular model parameters (esp. during personalization in mean/mode realization)

Returns:

attachment, regularity_vartorch.Tensor 1D (n_individuals,): The attachment and regularity (only for the current variable) at the end of this sampling step, per individual.

property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

property shape_adapted_std: tuple: Shape of adaptative variance.

validate_scale(scale: float | Tensor) → Tensor

Validate user provided scale in float or torch.Tensor form.

Scale of variable should always be positive (component-wise if multidimensional).

Parameters:

scalefloat or torch.Tensor: The scale to be validated.

Returns:

torch.Tensor: Valid scale.

class PopulationFastGibbsSampler(name: str, shape: tuple, *, scale: float | FloatTensor, random_order_dimension: bool = True, mean_acceptation_rate_target_bounds: Tuple[float, float] = (0.2, 0.4), adaptive_std_factor: float = 0.1, **base_sampler_kws)

Bases: AbstractPopulationGibbsSampler

Fast Gibbs sampler for population variables.

Note

The sampling batches along the dimensions except the first one. This speeds up sampling process for 2 dimensional parameters.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
scalefloat > 0 or torch.FloatTensor > 0: An approximate scale for the variable. It will be used to scale the initial adaptive std-dev used in sampler. An extra 1% factor will be applied on top of this scale (STD_SCALE_FACTOR) Note that if you pass a torch tensor, its shape should be compatible with shape of the variable.
random_order_dimensionbool (default True): This parameter controls whether we randomize the order of indices during the sampling loop. Article https://proceedings.neurips.cc/paper/2016/hash/e4da3b7fbbce2345d7772b0674a318d5-Abstract.html gives a rationale on why we should activate this flag.
mean_acceptation_rate_target_bounds:obj:`tuple`[lower_bound: float, upper_bound: float] with 0 < lower_bound < upper_bound < 1: Bounds on mean acceptation rate. Outside this range, the adaptation of the std-dev of sampler is triggered so to maintain a target acceptation rate in between these too bounds (e.g: ~30%).
adaptive_std_factorfloat in ]0, 1[: Factor by which we increase or decrease the std-dev of sampler when we are out of the custom bounds for the mean acceptation rate. We decrease it by 1 - factor if too low, and increase it with 1 + factor if too high.
**base_sampler_kws: Keyword arguments passed to AbstractSampler init method. In particular, you may pass the acceptation_history_length hyperparameter.

Attributes:

shape_acceptation
shape_adapted_std: Shape of adaptative variance.

Methods

`sample`(data, model, realizations, ...)	For each dimension (1D or 2D) of the population variable, compute current attachment and regularity.
`validate_scale`(scale)	Validate user provided scale in `float` or `torch.Tensor` form.

STD_SCALE_FACTOR: ClassVar[float] = 0.01

sample(data: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

For each dimension (1D or 2D) of the population variable, compute current attachment and regularity.

Propose a new value for the given dimension of the given population variable, and compute new attachment and regularity.

Do a MH step, keeping if better, or if worse with a probability.

Parameters:

dataDataset: Dataset used for sampling.
modelAbstractModel: Model for which to sample a random variable.
realizationsCollectionRealization: Realization state.
temperature_invfloat > 0: The temperature to use.
**attachment_computation_kws: Currently not used for population parameters.

Returns:

attachment, regularity_vartorch.Tensor 0D (scalars): The attachment and regularity (only for the current variable) at the end of this sampling step (summed on all individuals).

property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

property shape_adapted_std: tuple: Shape of adaptative variance.

validate_scale(scale: float | Tensor) → Tensor

Validate user provided scale in float or torch.Tensor form.

If necessary, scale is casted to a torch.Tensor.

Parameters:

scalefloat or torch.Tensor: The scale to be validated.

Returns:

torch.Tensor: Valid scale.

class PopulationGibbsSampler(name: str, shape: tuple, *, scale: float | FloatTensor, random_order_dimension: bool = True, mean_acceptation_rate_target_bounds: Tuple[float, float] = (0.2, 0.4), adaptive_std_factor: float = 0.1, **base_sampler_kws)

Bases: AbstractPopulationGibbsSampler

Gibbs sampler for population variables.

The sampling is done iteratively for all coordinate values.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
scalefloat > 0 or torch.FloatTensor > 0: An approximate scale for the variable. It will be used to scale the initial adaptive std-dev used in sampler. An extra 1% factor will be applied on top of this scale (STD_SCALE_FACTOR) Note that if you pass a torch tensor, its shape should be compatible with shape of the variable.
random_order_dimensionbool (default True): This parameter controls whether we randomize the order of indices during the sampling loop. Article https://proceedings.neurips.cc/paper/2016/hash/e4da3b7fbbce2345d7772b0674a318d5-Abstract.html gives a rationale on why we should activate this flag.
mean_acceptation_rate_target_bounds:obj:`tuple`[lower_bound: float, upper_bound: float] with 0 < lower_bound < upper_bound < 1: Bounds on mean acceptation rate. Outside this range, the adaptation of the std-dev of sampler is triggered so to maintain a target acceptation rate in between these too bounds (e.g: ~30%).
adaptive_std_factorfloat in ]0, 1[: Factor by which we increase or decrease the std-dev of sampler when we are out of the custom bounds for the mean acceptation rate. We decrease it by 1 - factor if too low, and increase it with 1 + factor if too high.
**base_sampler_kws: Keyword arguments passed to AbstractSampler.__init__() method. In particular, you may pass the acceptation_history_length hyperparameter.

Attributes:

shape_acceptation
shape_adapted_std: Shape of adaptative variance.

Methods

`sample`(data, model, realizations, ...)	For each dimension (1D or 2D) of the population variable, compute current attachment and regularity.
`validate_scale`(scale)	Validate user provided scale in `float` or `torch.Tensor` form.

STD_SCALE_FACTOR: ClassVar[float] = 0.01

sample(data: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

For each dimension (1D or 2D) of the population variable, compute current attachment and regularity.

Propose a new value for the given dimension of the given population variable, and compute new attachment and regularity.

Do a MH step, keeping if better, or if worse with a probability.

Parameters:

dataDataset: Dataset used for sampling.
modelAbstractModel: Model for which to sample a random variable.
realizationsCollectionRealization: Realization state.
temperature_invfloat > 0: The temperature to use.
**attachment_computation_kws: Currently not used for population parameters.

Returns:

attachment, regularity_vartorch.Tensor 0D (scalars): The attachment and regularity (only for the current variable) at the end of this sampling step (summed on all individuals).

property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

property shape_adapted_std: tuple: Shape of adaptative variance.

validate_scale(scale: float | Tensor) → Tensor

Validate user provided scale in float or torch.Tensor form.

If necessary, scale is casted to a torch.Tensor.

Parameters:

scalefloat or torch.Tensor: The scale to be validated.

Returns:

torch.Tensor: Valid scale.

class PopulationMetropolisHastingsSampler(name: str, shape: tuple, *, scale: float | FloatTensor, random_order_dimension: bool = True, mean_acceptation_rate_target_bounds: Tuple[float, float] = (0.2, 0.4), adaptive_std_factor: float = 0.1, **base_sampler_kws)

Bases: AbstractPopulationGibbsSampler

Metropolis-Hastings sampler for population variables.

Note

The sampling is done for all values at once. This speeds up considerably sampling but usually requires more iterations.

Parameters:

namestr: The name of the random variable to sample.
shapetuple of int: The shape of the random variable to sample.
scalefloat > 0 or torch.FloatTensor > 0: An approximate scale for the variable. It will be used to scale the initial adaptive std-dev used in sampler. An extra 1% factor will be applied on top of this scale (STD_SCALE_FACTOR) Note that if you pass a torch tensor, its shape should be compatible with shape of the variable.
random_order_dimensionbool (default True): This parameter controls whether we randomize the order of indices during the sampling loop. Article https://proceedings.neurips.cc/paper/2016/hash/e4da3b7fbbce2345d7772b0674a318d5-Abstract.html gives a rationale on why we should activate this flag.
mean_acceptation_rate_target_bounds:obj:`tuple`[lower_bound: float, upper_bound: float] with 0 < lower_bound < upper_bound < 1: Bounds on mean acceptation rate. Outside this range, the adaptation of the std-dev of sampler is triggered so to maintain a target acceptation rate in between these too bounds (e.g: ~30%).
adaptive_std_factorfloat in ]0, 1[: Factor by which we increase or decrease the std-dev of sampler when we are out of the custom bounds for the mean acceptation rate. We decrease it by 1 - factor if too low, and increase it with 1 + factor if too high.
**base_sampler_kws: Keyword arguments passed to AbstractSampler init method. In particular, you may pass the acceptation_history_length hyperparameter.

Attributes:

shape_acceptation
shape_adapted_std: Shape of adaptative variance.

Methods

`sample`(data, model, realizations, ...)	For each dimension (1D or 2D) of the population variable, compute current attachment and regularity.
`validate_scale`(scale)	Validate user provided scale in `float` or `torch.Tensor` form.

STD_SCALE_FACTOR: ClassVar[float] = 0.01

sample(data: Dataset, model: AbstractModel, realizations: CollectionRealization, temperature_inv: float, **attachment_computation_kws) → Tuple[Tensor, Tensor]

For each dimension (1D or 2D) of the population variable, compute current attachment and regularity.

Propose a new value for the given dimension of the given population variable, and compute new attachment and regularity.

Do a MH step, keeping if better, or if worse with a probability.

Parameters:

dataDataset: Dataset used for sampling.
modelAbstractModel: Model for which to sample a random variable.
realizationsCollectionRealization: Realization state.
temperature_invfloat > 0: The temperature to use.
**attachment_computation_kws: Currently not used for population parameters.

Returns:

attachment, regularity_vartorch.Tensor 0D (scalars): The attachment and regularity (only for the current variable) at the end of this sampling step (summed on all individuals).

property shape_acceptation: Tuple[int, ...]

Return the shape of acceptation tensor for a single iteration.

Returns:

tuple of int: The shape of the acceptation history.

property shape_adapted_std: tuple: Shape of adaptative variance.

validate_scale(scale: float | Tensor) → Tensor

Validate user provided scale in float or torch.Tensor form.

If necessary, scale is casted to a torch.Tensor.

Parameters:

scalefloat or torch.Tensor: The scale to be validated.

Returns:

torch.Tensor: Valid scale.

sampler_factory(sampler: str | AbstractSampler, variable_type: VariableType, **kwargs) → AbstractSampler

Factory for Samplers.

Parameters:

samplerAbstractSampler or str: If an instance of a subclass of AbstractSampler, returns the instance (no copy). If a string, returns a new instance of the appropriate class (with optional parameters kwargs).
variable_typeVariableType: The type of random variable that the sampler is supposed to sample.
**kwargs: Optional parameters for initializing the requested Sampler (not used if input is a subclass of AbstractSampler).

Returns:

AbstractSampler: The desired sampler.

Raises:

LeaspyAlgoInputError:: If the sampler provided is not supported.