Probabilistic distributions

class hy2dl.utils.distributions.AsymmetricLaplaceMixture

Bases: BaseDistribution

Asymmetric Laplace mixture distribution.

backtransform_parameters(params: dict[str, Tensor], target_scaler: dict[str, Tensor]) → dict[str, Tensor]

Back-transform parameters from the standardized space to the original space.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, in the standardized space, with shape [B, N, K, T] for each parameter

  • target_scaler (dict[str, torch.Tensor]) – Dictionary containing the mean and standard deviation of the target variables, with shape [T] for each variable.

Returns:

Dictionary containing the parameters of the mixture distribution, in the original space, with shape [B, N, K, T] for each parameter

Return type:

dict[str, torch.Tensor]

calc_cdf(params: dict[str, Tensor], weights: Tensor, x: Tensor) → Tensor

Calculate the cumulative distribution function (CDF) of the mixture distribution at the given value x.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Value at which to evaluate the CDF, with shape [B, N, T].

Returns:

CDF evaluated at x, with shape [B, N, T].

Return type:

torch.Tensor

calc_logpdf(params: dict[str, Tensor], weights: Tensor, x: Tensor) → Tensor

Calculate the log probability density function (log PDF) of the mixture distribution at the given value x.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Value at which to evaluate the CDF, with shape [B, N, T].

Returns:

log PDF evaluated at x, with shape [B, N, T].

Return type:

torch.Tensor

map_parameters(raw_params: Tensor, num_mixture_components: int, num_targets: int) → dict[str, Tensor]

Map LSTM output to the distribution parameters

Parameters:

  • raw_params (torch.Tensor) – Raw parameters output by the model, with shape [B, N, K * T] for each parameter.

  • num_mixture_components (int) – Number of mixture components (K).

  • num_targets (int) – Number of target variables (T).

Returns:

Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter.

Return type:

dict[str, torch.Tensor]

mean(params: dict[str, Tensor], weights: Tensor) → Tensor

Calculate the mean of the mixture distribution given its parameters.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

Returns:

Mean of the mixture distribution, with shape [B, N, T]

Return type:

torch.Tensor

property parameters: tuple[str]

Return an iterator over module parameters.

This is typically passed to an optimizer.

Parameters:

recurse (bool) – if True, then yields parameters of this module and all submodules. Otherwise, yields only parameters that are direct members of this module.

Yields:

Parameter – module parameter

Example:

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)
sample(params: dict[str, Tensor], weights: Tensor, num_samples: int) → Tensor

Generate samples from the mixture distribution.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • num_samples (int) – Number of samples to generate for each prediction step

Returns:

Generated samples of shape [B, N, S, T]

Return type:

torch.Tensor

class hy2dl.utils.distributions.BaseDistribution

Bases: Module

Base class for mixture distributions.

Notation

  • B: batch_size

  • L: seq_length

  • N: predict_last_n

  • K: num_mixture_components

  • T: num_targets

  • S: num_samples

  • Q: num_quantiles

backtransform_parameters(params: dict[str, Tensor], target_scaler: dict[str, Tensor]) → dict[str, Tensor]

Back-transform parameters from the standardized space to the original space.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, in the standardized space, with shape [B, N, K, T] for each parameter

  • target_scaler (dict[str, torch.Tensor]) – Dictionary containing the mean and standard deviation of the target variables, with shape [T] for each variable.

Returns:

Dictionary containing the parameters of the mixture distribution, in the original space, with shape [B, N, K, T] for each parameter

Return type:

dict[str, torch.Tensor]

calc_cdf(params: dict[str, Tensor], weights: Tensor, x: Tensor) → Tensor

Calculate the cumulative distribution function (CDF) of the mixture distribution at the given value x.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Value at which to evaluate the CDF, with shape [B, N, T].

Returns:

CDF evaluated at x, with shape [B, N, T].

Return type:

torch.Tensor

calc_logpdf(params: dict[str, Tensor], weights: Tensor, x: Tensor) → Tensor

Calculate the log probability density function (log PDF) of the mixture distribution at the given value x.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Value at which to evaluate the CDF, with shape [B, N, T].

Returns:

log PDF evaluated at x, with shape [B, N, T].

Return type:

torch.Tensor

map_parameters(raw_params: dict[str, Tensor], num_mixture_components: int, num_targets: int) → dict[str, Tensor]

Map LSTM output to the distribution parameters

Parameters:

  • raw_params (torch.Tensor) – Raw parameters output by the model, with shape [B, N, K * T] for each parameter.

  • num_mixture_components (int) – Number of mixture components (K).

  • num_targets (int) – Number of target variables (T).

Returns:

Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter.

Return type:

dict[str, torch.Tensor]

mean(params: dict[str, Tensor], weights: Tensor) → Tensor

Calculate the mean of the mixture distribution given its parameters.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

Returns:

Mean of the mixture distribution, with shape [B, N, T]

Return type:

torch.Tensor

property parameters: tuple[str]

Return an iterator over module parameters.

This is typically passed to an optimizer.

Parameters:

recurse (bool) – if True, then yields parameters of this module and all submodules. Otherwise, yields only parameters that are direct members of this module.

Yields:

Parameter – module parameter

Example:

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)
pit(params: dict[str, Tensor], weights: Tensor, x: Tensor, bins: Tensor, average: bool = True) → Tensor

Calculate the probability integral transform (PIT) values for the given observations x under the predicted mixture distribution.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Observed values for which to calculate the PIT, with shape [B, N, T].

  • bins (torch.Tensor) – Bin edges for the PIT histogram, with shape [num_bins + 1].

  • average (bool, default=True) – Whether to average the PIT values across the B (batch) dimension or return them separately.

Returns:

PIT values for each T.

Return type:

list[torch.Tensor]

quantile(params: dict[str, Tensor], weights: Tensor, q: list[float], max_iter: int = 50, tol: float = 0.001) → Tensor

Compute quantiles of the predicted mixture distribution using Newton’s method.

Iteratively solves F(x) = q for x, for each quantile probability q, where F is the mixture CDF. Uses Newton-Raphson iteration: x_{n+1} = x_n - (F(x_n) - q) / f(x_n) where f is the PDF.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • q (list[float]) – List of quantile probabilities (between 0 and 1)

  • max_iter (int, default=50) – Maximum number of Newton iterations

  • tol (float, default=1e-3) – Convergence tolerance for Newton’s method

Returns:

Quantile values of shape [B, N, Q, T]

Return type:

torch.Tensor

sample(params: dict[str, Tensor], weights: Tensor, num_samples: int) → Tensor

Generate samples from the mixture distribution.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • num_samples (int) – Number of samples to generate for each prediction step

Returns:

Generated samples of shape [B, N, S, T]

Return type:

torch.Tensor

class hy2dl.utils.distributions.GaussianMixture

Bases: BaseDistribution

Gaussian mixture distribution.

backtransform_parameters(params: dict[str, Tensor], target_scaler: dict[str, Tensor]) → dict[str, Tensor]

Back-transform parameters from the standardized space to the original space.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, in the standardized space, with shape [B, N, K, T] for each parameter

  • target_scaler (dict[str, torch.Tensor]) – Dictionary containing the mean and standard deviation of the target variables, with shape [T] for each variable.

Returns:

Dictionary containing the parameters of the mixture distribution, in the original space, with shape [B, N, K, T] for each parameter

Return type:

dict[str, torch.Tensor]

calc_cdf(params: dict[str, Tensor], weights: Tensor, x: Tensor) → Tensor

Calculate the cumulative distribution function (CDF) of the mixture distribution at the given value x.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Value at which to evaluate the CDF, with shape [B, N, T].

Returns:

CDF evaluated at x, with shape [B, N, T].

Return type:

torch.Tensor

calc_logpdf(params: dict[str, Tensor], weights: Tensor, x: Tensor) → Tensor

Calculate the log probability density function (log PDF) of the mixture distribution at the given value x.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • x (torch.Tensor) – Value at which to evaluate the CDF, with shape [B, N, T].

Returns:

log PDF evaluated at x, with shape [B, N, T].

Return type:

torch.Tensor

map_parameters(raw_params: Tensor, num_mixture_components: int, num_targets: int) → dict[str, Tensor]

Map LSTM output to the distribution parameters

Parameters:

  • raw_params (torch.Tensor) – Raw parameters output by the model, with shape [B, N, K * T] for each parameter.

  • num_mixture_components (int) – Number of mixture components (K).

  • num_targets (int) – Number of target variables (T).

Returns:

Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter.

Return type:

dict[str, torch.Tensor]

mean(params: dict[str, Tensor], weights: Tensor) → Tensor

Calculate the mean of the mixture distribution given its parameters.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

Returns:

Mean of the mixture distribution, with shape [B, N, T]

Return type:

torch.Tensor

property parameters: tuple[str]

Return an iterator over module parameters.

This is typically passed to an optimizer.

Parameters:

recurse (bool) – if True, then yields parameters of this module and all submodules. Otherwise, yields only parameters that are direct members of this module.

Yields:

Parameter – module parameter

Example:

>>> # xdoctest: +SKIP("undefined vars")
>>> for param in model.parameters():
>>>     print(type(param), param.size())
<class 'torch.Tensor'> (20L,)
<class 'torch.Tensor'> (20L, 1L, 5L, 5L)
sample(params: dict[str, Tensor], weights: Tensor, num_samples: int) → Tensor

Generate samples from the mixture distribution.

Parameters:

  • params (dict[str, torch.Tensor]) – Dictionary containing the parameters of the mixture distribution, with shape [B, N, K, T] for each parameter

  • weights (torch.Tensor) – Mixture weights, with shape [B, N, K, T].

  • num_samples (int) – Number of samples to generate for each prediction step

Returns:

Generated samples of shape [B, N, S, T]

Return type:

torch.Tensor