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