MQF2Distribution

class pytorch_forecasting.metrics._mqf2_utils.MQF2Distribution(picnn: Module, hidden_state: Tensor, prediction_length: int, is_energy_score: bool = True, es_num_samples: int = 50, beta: float = 1.0, threshold_input: float = 100.0, validate_args: bool = False)

Bases: Distribution

Distribution class for the model MQF2 proposed in the paper Multivariate Quantile Function Forecaster by Kan, Aubet, Januschowski, Park, Benidis, Ruthotto, Gasthaus

Parameters:

• picnn – A SequentialNet instance of a partially input convex neural network (picnn)

• hidden_state – hidden_state obtained by unrolling the RNN encoder shape = (batch_size, context_length, hidden_size) in training shape = (batch_size, hidden_size) in inference

• prediction_length – Length of the prediction horizon

• is_energy_score – If True, use energy score as objective function otherwise use maximum likelihood as objective function (normalizing flows)

• es_num_samples – Number of samples drawn to approximate the energy score

• beta – Hyperparameter of the energy score (power of the two terms)

• threshold_input – Clamping threshold of the (scaled) input when maximum likelihood is used as objective function this is used to make the forecaster more robust to outliers in training samples

• validate_args – Sets whether validation is enabled or disabled For more details, refer to the descriptions in torch.distributions.distribution.Distribution

Inherited-members:

Methods

cdf(value)	Returns the cumulative density/mass function evaluated at value.
energy_score(z)	Computes the (approximated) energy score sum_i ES(g,z_i), where ES(g,z_i) = -1/(2*es_num_samples^2) * sum_{w,w'} ||w-w'||_2^beta + 1/es_num_samples * sum_{w''} ||w''-z_i||_2^beta, w's are samples drawn from the quantile function g(., h_i) (gradient of picnn), h_i is the hidden state associated with z_i, and es_num_samples is the number of samples drawn for each of w, w', w'' in energy score approximation
entropy()	Returns entropy of distribution, batched over batch_shape.
enumerate_support([expand])	Returns tensor containing all values supported by a discrete distribution.
expand(batch_shape[, _instance])	Returns a new distribution instance (or populates an existing instance provided by a derived class) with batch dimensions expanded to batch_shape.
get_numel(tensor_shape)
icdf(value)	Returns the inverse cumulative density/mass function evaluated at value.
log_prob(z)	Computes the log likelihood log(g(z)) + logdet(dg(z)/dz), where g is the gradient of the picnn
loss(z)
perplexity()	Returns perplexity of distribution, batched over batch_shape.
quantile(alpha[, hidden_state])	Generates the predicted paths associated with the quantile levels alpha
rsample([sample_shape])	Generates the sample paths
sample([sample_shape])	Generates a sample_shape shaped sample or sample_shape shaped batch of samples if the distribution parameters are batched.
sample_n(n)	Generates n samples or n batches of samples if the distribution parameters are batched.
set_default_validate_args(value)	Sets whether validation is enabled or disabled.
stack_sliding_view(z)	Auxiliary function for loss computation Unfolds the observations by sliding a window of size prediction_length over the observations z Then, reshapes the observations into a 2-dimensional tensor for further computation

Attributes

arg_constraints	Returns a dictionary from argument names to Constraint objects that should be satisfied by each argument of this distribution.
batch_shape	Returns the shape over which parameters are batched.
event_dim
event_shape	Returns the shape of a single sample (without batching).
has_enumerate_support
has_rsample
mean	Returns the mean of the distribution.
mode	Returns the mode of the distribution.
stddev	Returns the standard deviation of the distribution.
support	Returns a Constraint object representing this distribution's support.
variance	Returns the variance of the distribution.

energy_score(z: Tensor) → Tensor

Computes the (approximated) energy score sum_i ES(g,z_i), where ES(g,z_i) = -1/(2*es_num_samples^2) * sum_{w,w’} ||w-w’||_2^beta + 1/es_num_samples * sum_{w’’} ||w’’-z_i||_2^beta, w’s are samples drawn from the quantile function g(., h_i) (gradient of picnn), h_i is the hidden state associated with z_i, and es_num_samples is the number of samples drawn for each of w, w’, w’’ in energy score approximation

Parameters:

z – A batch of time series with shape (batch_size, context_length + prediction_length - 1)

Returns:

Tensor of shape (batch_size * context_length,)

Return type:

loss

log_prob(z: Tensor) → Tensor

Computes the log likelihood log(g(z)) + logdet(dg(z)/dz), where g is the gradient of the picnn

Parameters:

z – A batch of time series with shape (batch_size, context_length + prediciton_length - 1)

Returns:

Tesnor of shape (batch_size * context_length,)

Return type:

loss

quantile(alpha: Tensor, hidden_state: Tensor | None = None) → Tensor

Generates the predicted paths associated with the quantile levels alpha

Parameters:

• alpha – quantile levels, shape = (batch_shape, prediction_length)

• hidden_state – hidden_state, shape = (batch_shape, hidden_size)

Returns:

predicted paths of shape = (batch_shape, prediction_length)

Return type:

results

rsample(sample_shape: Size = ()) → Tensor

Generates the sample paths

Parameters:

sample_shape – Shape of the samples

Returns:

Tesnor of shape (batch_size, * sample_shape, prediction_length)

Return type:

sample_paths

stack_sliding_view(z: Tensor) → Tensor

Auxiliary function for loss computation Unfolds the observations by sliding a window of size prediction_length over the observations z Then, reshapes the observations into a 2-dimensional tensor for further computation

Parameters:

z – A batch of time series with shape (batch_size, context_length + prediction_length - 1)

Returns:

Unfolded time series with shape (batch_size * context_length, prediction_length)

Return type:

Tensor

property batch_shape: Size

Returns the shape over which parameters are batched.

property event_shape: tuple

Returns the shape of a single sample (without batching).