gluonts.torch.distributions.isqf module#

class gluonts.torch.distributions.isqf.ISQF(spline_knots: torch.Tensor, spline_heights: torch.Tensor, beta_l: torch.Tensor, beta_r: torch.Tensor, qk_y: torch.Tensor, qk_x: torch.Tensor, tol: float = 0.0001, validate_args: bool = False)[source]#

Bases: torch.distributions.distribution.Distribution

Distribution class for the Incremental (Spline) Quantile Function in the paper Learning Quantile Functions without Quantile Crossing for Distribution-free Time Series Forecasting by Park, Robinson, Aubet, Kan, Gasthaus, Wang :param spline_knots: Tensor parametrizing the x-positions (y-positions) of the spline knots

Shape: (*batch_shape, (num_qk-1), num_pieces)

Parameters

  • spline_heights – Tensor parametrizing the x-positions (y-positions) of the spline knots Shape: (*batch_shape, (num_qk-1), num_pieces)

  • qk_x – Tensor containing the increasing x-positions (y-positions) of the quantile knots, Shape: (*batch_shape, num_qk)

  • qk_y – Tensor containing the increasing x-positions (y-positions) of the quantile knots, Shape: (*batch_shape, num_qk)

  • beta_l – Tensor containing the non-negative learnable parameter of the left (right) tail, Shape: (*batch_shape,)

  • beta_r – Tensor containing the non-negative learnable parameter of the left (right) tail, Shape: (*batch_shape,)

property batch_shape: torch.Size#

Returns the shape over which parameters are batched.

cdf(z: torch.Tensor) → torch.Tensor[source]#

Computes the quantile level alpha_tilde such that q(alpha_tilde) = z :param z: Tensor of shape = (*batch_shape,)

Returns

Tensor of shape = (*batch_shape,)

Return type

alpha_tilde

cdf_spline(z: torch.Tensor) → torch.Tensor[source]#

For observations z and splines defined in [qk_x[k], qk_x[k+1]] Computes the quantile level alpha_tilde such that alpha_tilde.

= q^{-1}(z) if z is in-between qk_x[k] and qk_x[k+1] = qk_x[k] if z<qk_x[k] = qk_x[k+1] if z>qk_x[k+1] :param z: Observation, shape = (*batch_shape,)

Returns

Corresponding quantile level, shape = (*batch_shape, num_qk-1)

Return type

alpha_tilde

cdf_tail(z: torch.Tensor, left_tail: bool = True) → torch.Tensor[source]#

Computes the quantile level alpha_tilde such that alpha_tilde.

= q^{-1}(z) if z is in the tail region = qk_x_l or qk_x_r if z is in the non-tail region :param z: Observation, shape = (*batch_shape,) :param left_tail: If True, compute alpha_tilde for the left tail

Otherwise, compute alpha_tilde for the right tail

Returns

Corresponding quantile level, shape = (*batch_shape,)

Return type

alpha_tilde

crps(z: torch.Tensor) → torch.Tensor[source]#

Compute CRPS in analytical form :param z: Observation to evaluate. Shape = (*batch_shape,)

Returns

Tensor containing the CRPS, of the same shape as z

Return type

Tensor

crps_spline(z: torch.Tensor) → torch.Tensor[source]#

Compute CRPS in analytical form for the spline :param z: Observation to evaluate. shape = (*batch_shape,)

Returns

Tensor containing the CRPS, of the same shape as z

Return type

Tensor

crps_tail(z: torch.Tensor, left_tail: bool = True) → torch.Tensor[source]#

Compute CRPS in analytical form for left/right tails :param z: Observation to evaluate. shape = (*batch_shape,) :param left_tail: If True, compute CRPS for the left tail

Otherwise, compute CRPS for the right tail

Returns

Tensor containing the CRPS, of the same shape as z

Return type

Tensor

loss(z: torch.Tensor) → torch.Tensor[source]#
static parameterize_qk(quantile_knots: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor][source]#

Function to parameterize the x or y positions of the num_qk quantile knots :param quantile_knots: x or y positions of the quantile knots

shape: (*batch_shape, num_qk)

Returns

  • qk – x or y positions of the quantile knots (qk), with index=1, …, num_qk-1, shape: (*batch_shape, num_qk-1)

  • qk_plus – x or y positions of the quantile knots (qk), with index=2, …, num_qk, shape: (*batch_shape, num_qk-1)

  • qk_l – x or y positions of the left-most quantile knot (qk), shape: (*batch_shape)

  • qk_r – x or y positions of the right-most quantile knot (qk), shape: (*batch_shape)

static parameterize_spline(spline_knots: torch.Tensor, qk: torch.Tensor, qk_plus: torch.Tensor, tol: float = 0.0001) → Tuple[torch.Tensor, torch.Tensor][source]#

Function to parameterize the x or y positions of the spline knots :param spline_knots: variable that parameterizes the spline knot positions :param qk: x or y positions of the quantile knots (qk),

with index=1, …, num_qk-1, shape: (*batch_shape, num_qk-1)

Parameters

  • qk_plus – x or y positions of the quantile knots (qk), with index=2, …, num_qk, shape: (*batch_shape, num_qk-1)

  • num_pieces – number of spline knot pieces

  • tol – tolerance hyperparameter for numerical stability

Returns

  • sk – x or y positions of the spline knots (sk), shape: (*batch_shape, num_qk-1, num_pieces)

  • delta_sk – difference of x or y positions of the spline knots (sk), shape: (*batch_shape, num_qk-1, num_pieces)

static parameterize_tail(beta: torch.Tensor, qk_x: torch.Tensor, qk_y: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor][source]#

Function to parameterize the tail parameters Note that the exponential tails are given by q(alpha)

= a_l log(alpha) + b_l if left tail = a_r log(1-alpha) + b_r if right tail where a_l=1/beta_l, b_l=-a_l*log(qk_x_l)+q(qk_x_l) a_r=1/beta_r, b_r=a_r*log(1-qk_x_r)+q(qk_x_r) :param beta: parameterizes the left or right tail, shape: (*batch_shape,) :param qk_x: left- or right-most x-positions of the quantile knots,

shape: (*batch_shape,)

Parameters

qk_y – left- or right-most y-positions of the quantile knots, shape: (*batch_shape,)

Returns

  • tail_a – a_l or a_r as described above

  • tail_b – b_l or b_r as described above

quantile(alpha: torch.Tensor) → torch.Tensor[source]#
quantile_internal(alpha: torch.Tensor, dim: Optional[int] = None) → torch.Tensor[source]#

Evaluates the quantile function at the quantile levels input_alpha :param alpha: Tensor of shape = (*batch_shape,) if axis=None, or containing an

additional axis on the specified position, otherwise

Parameters

dim – Index of the axis containing the different quantile levels which are to be computed. Read the description below for detailed information

Returns

Quantiles tensor, of the same shape as alpha

Return type

Tensor

quantile_spline(alpha: torch.Tensor, dim: Optional[int] = None) → torch.Tensor[source]#
quantile_tail(alpha: torch.Tensor, dim: Optional[int] = None, left_tail: bool = True) → torch.Tensor[source]#
rsample(sample_shape: torch.Size = torch.Size([])) → torch.Tensor[source]#

Function used to draw random samples :param num_samples: number of samples :param dtype: data type

Returns

Tensor of shape (*batch_shape,) if num_samples = None else (num_samples, *batch_shape)

Return type

Tensor

class gluonts.torch.distributions.isqf.ISQFOutput(num_pieces: int, qk_x: List[float], tol: float = 0.0001)[source]#

Bases: gluonts.torch.distributions.distribution_output.DistributionOutput

DistributionOutput class for the Incremental (Spline) Quantile Function :param num_pieces: number of spline pieces for each spline

ISQF reduces to IQF when num_pieces = 1

Parameters

  • qk_x – List containing the x-positions of quantile knots

  • tol – tolerance for numerical safeguarding

distr_cls#

alias of gluonts.torch.distributions.isqf.ISQF

distribution(distr_args, loc: Optional[torch.Tensor] = None, scale: Optional[torch.Tensor] = None) → gluonts.torch.distributions.isqf.ISQF[source]#

function outputing the distribution class distr_args: distribution arguments loc: shift to the data mean scale: scale to the data

classmethod domain_map(spline_knots: torch.Tensor, spline_heights: torch.Tensor, beta_l: torch.Tensor, beta_r: torch.Tensor, quantile_knots: torch.Tensor, tol: float = 0.0001) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor][source]#

Domain map function The inputs of this function are specified by self.args_dim.

spline_knots, spline_heights: parameterizing the x-/ y-positions of the spline knots, shape = (*batch_shape, (num_qk-1)*num_pieces)

beta_l, beta_r: parameterizing the left/right tail, shape = (*batch_shape, 1)

quantile_knots: parameterizing the y-positions of the quantile knots, shape = (*batch_shape, num_qk)

property event_shape: Tuple#

Shape of each individual event compatible with the output object.

reshape_spline_args(distr_args, qk_x: List[float])[source]#

auxiliary function reshaping knots and heights to (*batch_shape, num_qk-1, num_pieces) qk_x to (*batch_shape, num_qk)

class gluonts.torch.distributions.isqf.TransformedISQF(base_distribution: gluonts.torch.distributions.isqf.ISQF, transforms: List[torch.distributions.transforms.AffineTransform], validate_args=None)[source]#

Bases: torch.distributions.transformed_distribution.TransformedDistribution

crps(y: torch.Tensor) → torch.Tensor[source]#