gluonts.mx.distribution.empirical_distribution module#

class gluonts.mx.distribution.empirical_distribution.EmpiricalDistribution(samples: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], event_dim: int)[source]#

Bases: gluonts.mx.distribution.distribution.Distribution

A class representing empirical distribution.

The target can be vector/tensor-valued, i.e., event_shape can be larger than or equal to 1. However, note that each dimension is assumed to be independent when computing variance and CRPS loss.

Also, for computing CDF and quantiles, it is assumede that samples are distinct along the samples dimension, which should almost always be the case if samples are drawn from continuous distributions.

Parameters

  • samples – Tensor containing samples, of shape (num_samples, *batch_shape, *event_shape).

  • event_dim – 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 F#
arg_names: Tuple#
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(x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol])[source]#

Return the value of the cumulative distribution function evaluated at x.

crps_univariate(x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]#

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

The last dimension of obs specifies the “event dimension” of the target (= 1 for the univariate case). For multivariate target, CRSP scores are computed for each dimension separately and then their sum is returned.

Parameters

x – Tensor of ground truth with shape (*batch_shape, *event_shape)

Returns

CRPS score of shape (*batch_shape, 1).

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.

loss(x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.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

property mean: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]#

Tensor containing the mean of the distribution.

quantile(level: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.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_losses(obs: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], quantiles: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], levels: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]#

Computes quantile losses for all the quantiles specified.

Parameters

  • obs – Ground truth observation. Shape: (batch_size, seq_len, *event_shape)

  • quantiles – Quantile values. Shape: (batch_size, seq_len, *event_shape, num_quantiles)

  • levels – Quantile levels. Shape: (batch_size, seq_len, *event_shape, num_quantiles)

Returns

Quantile losses of shape: (batch_size, seq_len, *event_shape, num_quantiles)

Return type

Tensor

sample(num_samples: typing.Optional[int] = None, dtype=<class 'numpy.float32'>) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]#

Draw samples from the distribution.

If num_samples is given the first dimension of the output will be num_samples.

Parameters

  • num_samples – Number of samples to to be drawn.

  • dtype – Data-type of the samples.

Returns

A tensor containing samples. This has shape (*batch_shape, *eval_shape) if num_samples = None and (num_samples, *batch_shape, *eval_shape) otherwise.

Return type

Tensor

property stddev: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]#

Tensor containing the standard deviation of the distribution.

class gluonts.mx.distribution.empirical_distribution.EmpiricalDistributionOutput(num_samples: int, distr_output: gluonts.mx.distribution.distribution_output.DistributionOutput)[source]#

Bases: gluonts.mx.distribution.distribution_output.DistributionOutput

This allows us to wrap EmpiricalDistribution by any parametric distribution and learn the parameters by minimizing CRPS loss on the samples of EmpiricalDistribution.

See the inference test test_empirical_distribution in test.distribution.test_mx_distribution_inference which checks if the CRPS loss is correctly implemented.

args_dim: Dict[str, int]#
distr_cls: type#
distribution(distr_args, loc: Optional[Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]] = None, scale: Optional[Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]] = None) → gluonts.mx.distribution.distribution.Distribution[source]#

Construct the associated distribution, given the collection of constructor arguments and, optionally, a scale tensor.

Parameters

  • distr_args – Constructor arguments for the underlying Distribution type.

  • loc – Optional tensor, of the same shape as the batch_shape+event_shape of the resulting distribution.

  • scale – Optional tensor, of the same shape as the batch_shape+event_shape of the resulting distribution.

domain_map(F, *args, **kwargs)[source]#

Converts arguments to the right shape and domain.

The domain depends on the type of distribution, while the correct shape is obtained by reshaping the trailing axis in such a way that the returned tensors define a distribution of the right event_shape.

property event_shape: Tuple#

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

get_args_proj(prefix: Optional[str] = None) → gluonts.mx.distribution.distribution_output.ArgProj[source]#