gluonts.torch.distributions.isqf module#

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

Bases: 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: Size#

Returns the shape over which parameters are batched.

cdf(z: Tensor) 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: Tensor) 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: Tensor, left_tail: bool = True) 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: Tensor) 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: Tensor) 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: Tensor, left_tail: bool = True) 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: Tensor) Tensor[source]#
static parameterize_qk(quantile_knots: Tensor) Tuple[Tensor, Tensor, Tensor, 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: Tensor, qk: Tensor, qk_plus: Tensor, tol: float = 0.0001) Tuple[Tensor, 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: Tensor, qk_x: Tensor, qk_y: Tensor) Tuple[Tensor, 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: Tensor) Tensor[source]#
quantile_internal(alpha: Tensor, dim: Optional[int] = None) 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: Tensor, dim: Optional[int] = None) Tensor[source]#
quantile_tail(alpha: Tensor, dim: Optional[int] = None, left_tail: bool = True) Tensor[source]#
rsample(sample_shape: Size = torch.Size([])) 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: 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 ISQF

distribution(distr_args, loc: Optional[Tensor] = None, scale: Optional[Tensor] = None) 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: Tensor, spline_heights: Tensor, beta_l: Tensor, beta_r: Tensor, quantile_knots: Tensor, tol: float = 0.0001) Tuple[Tensor, Tensor, Tensor, Tensor, 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: ISQF, transforms: List[AffineTransform], validate_args=None)[source]#

Bases: TransformedDistribution

crps(y: Tensor) Tensor[source]#