gluonts.mx.distribution.isqf module#

class gluonts.mx.distribution.isqf.ISQF(spline_knots: Union[NDArray, Symbol], spline_heights: Union[NDArray, Symbol], beta_l: Union[NDArray, Symbol], beta_r: Union[NDArray, Symbol], qk_y: Union[NDArray, Symbol], qk_x: Union[NDArray, Symbol], num_qk: int, num_pieces: int, tol: float = 0.0001)[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.

Parameters:

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

  • 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 F#
arg_names: Tuple#
property args: List#
property batch_shape: Tuple#

Layout of the set of events contemplated by the distribution.

Invoking sample() from a distribution yields a tensor of shape batch_shape + event_shape, and computing log_prob (or loss more in general) on such sample will yield a tensor of shape batch_shape.

This property is available in general only in mx.ndarray mode, when the shape of the distribution arguments can be accessed.

cdf(z: Union[NDArray, Symbol]) → Union[NDArray, Symbol][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: Union[NDArray, Symbol]) → Union[NDArray, Symbol][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: Union[NDArray, Symbol], left_tail: bool = True) → Union[NDArray, Symbol][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

Parameters:

  • z – Observation, shape = (*batch_shape,)

  • 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: Union[NDArray, Symbol]) → Union[NDArray, Symbol][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: Union[NDArray, Symbol]) → Union[NDArray, Symbol][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: Union[NDArray, Symbol], left_tail: bool = True) → Union[NDArray, Symbol][source]#

Compute CRPS in analytical form for left/right tails.

Parameters:

  • z – Observation to evaluate. shape = (*batch_shape,)

  • 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

property event_dim: int#

Number of event dimensions, i.e., length of the event_shape tuple.

This is 0 for distributions over scalars, 1 over vectors, 2 over matrices, and so on.

property event_shape: Tuple#

Shape of each individual event contemplated by the distribution.

For example, distributions over scalars have event_shape = (), over vectors have event_shape = (d, ) where d is the length of the vectors, over matrices have event_shape = (d1, d2), and so on.

Invoking sample() from a distribution yields a tensor of shape batch_shape + event_shape.

This property is available in general only in mx.ndarray mode, when the shape of the distribution arguments can be accessed.

is_reparameterizable = False#
loss(z: Union[NDArray, Symbol]) → Union[NDArray, Symbol][source]#

Compute the loss at x according to the distribution.

By default, this method returns the negative of log_prob. For some distributions, however, the log-density is not easily computable and therefore other loss functions are computed.

Parameters:

x – Tensor of shape (*batch_shape, *event_shape).

Returns:

Tensor of shape batch_shape containing the value of the loss for each event in x.

Return type:

Tensor

static parametrize_qk(F, quantile_knots: Union[NDArray, Symbol]) → Tuple[Union[NDArray, Symbol], Union[NDArray, Symbol], Union[NDArray, Symbol], Union[NDArray, Symbol]][source]#

Function to parametrize the x or y positions of the num_qk quantile knots.

Parameters:

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 parametrize_spline(F, spline_knots: Union[NDArray, Symbol], qk: Union[NDArray, Symbol], qk_plus: Union[NDArray, Symbol], num_pieces: int, tol: float = 0.0001) → Tuple[Union[NDArray, Symbol], Union[NDArray, Symbol]][source]#

Function to parametrize 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 parametrize_tail(F, beta: Union[NDArray, Symbol], qk_x: Union[NDArray, Symbol], qk_y: Union[NDArray, Symbol]) → Tuple[Union[NDArray, Symbol], Union[NDArray, Symbol]][source]#

Function to parametrize 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)

Parameters:

  • beta – parameterizes the left or right tail, shape: (*batch_shape,)

  • qk_x – left- or right-most x-positions of the quantile knots, shape: (*batch_shape,)

  • 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(input_alpha: Union[NDArray, Symbol]) → Union[NDArray, Symbol][source]#

Calculates quantiles for the given levels.

Parameters:

level – Level values to use for computing the quantiles. level should be a 1d tensor of level values between 0 and 1.

Returns:

Quantile values corresponding to the levels passed. The return shape is

(num_levels, …DISTRIBUTION_SHAPE…),

where DISTRIBUTION_SHAPE is the shape of the underlying distribution.

Return type:

quantiles

quantile_internal(alpha: Union[NDArray, Symbol], axis: Optional[int] = None) → Union[NDArray, Symbol][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:

axis – 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: Union[NDArray, Symbol], axis: Optional[int] = None) → Union[NDArray, Symbol][source]#

Evaluates the spline functions at the quantile levels contained in alpha.

Parameters:

  • alpha – Input quantile levels

  • axis – Axis along which to expand For details of input_alpha shape and axis, refer to the description in quantile_internal

Returns:

Quantiles tensor with shape = (*batch_shape, num_qk-1) if axis = None = (1, *batch_shape, num_qk-1) if axis = 0 = (*batch_shape, num_qk-1, num_pieces) if axis = -2

Return type:

Tensor

quantile_tail(alpha: Union[NDArray, Symbol], axis: Optional[int] = None, left_tail: bool = True) → Union[NDArray, Symbol][source]#

Evaluates the tail functions at the quantile levels contained in alpha :param alpha: Input quantile levels :param axis: Axis along which to expand

For details of input_alpha shape and axis, refer to the description in quantile_internal

Parameters:

left_tail – If True, compute the quantile for the left tail Otherwise, compute the quantile for the right tail

Returns:

Quantiles tensor, of the same shape as alpha

Return type:

Tensor

sample(num_samples: ~typing.Optional[int] = None, dtype=<class 'numpy.float32'>) → Union[NDArray, Symbol][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.mx.distribution.isqf.ISQFOutput(num_pieces: int, qk_x: List[float], tol: float = 0.0001)[source]#

Bases: DistributionOutput

DistributionOutput class for the Incremental (Spline) Quantile Function.

Parameters:

  • num_pieces – number of spline pieces for each spline ISQF reduces to IQF when num_pieces = 1

  • alpha – Tensor containing the x-positions of quantile knots

  • tol – tolerance for numerical safeguarding

distr_cls#

alias of ISQF

distribution(distr_args, loc: Optional[Union[NDArray, Symbol]] = None, scale: Optional[Union[NDArray, Symbol]] = 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(F, *args: Union[NDArray, Symbol], tol: float = 0.0001) → Tuple[Union[NDArray, Symbol], Union[NDArray, Symbol], Union[NDArray, Symbol], Union[NDArray, Symbol], Union[NDArray, Symbol]][source]#

Domain map function The inputs of this function are specified by self.args_dim knots, heights:

parameterizing the x-/ y-positions of the spline knots, shape = (*batch_shape, (num_qk-1)*num_pieces) q: parameterizing the y-positions of the quantile knots, shape = (*batch_shape, num_qk) beta_l, beta_r: parameterizing the left/right tail, shape = (*batch_shape, 1)

property event_shape: Tuple#

Shape of each individual event contemplated by the distributions that this object constructs.

reshape_spline_args(distr_args, qk_x)[source]#

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

class gluonts.mx.distribution.isqf.TransformedISQF(base_distribution: ISQF, transforms: List[Bijection])[source]#

Bases: TransformedDistribution, ISQF

crps(y: Union[NDArray, Symbol]) → Union[NDArray, Symbol][source]#

Compute the continuous rank probability score (CRPS) of x according to the distribution.

Parameters:

x – Tensor of shape (*batch_shape, *event_shape).

Returns:

Tensor of shape batch_shape containing the CRPS score, according to the distribution, for each event in x.

Return type:

Tensor