# gluonts.mx.distribution.lowrank_multivariate_gaussian module¶

class gluonts.mx.distribution.lowrank_multivariate_gaussian.LowrankMultivariateGaussian(dim: int, rank: int, mu: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], D: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], W: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol])[source]

Multivariate Gaussian distribution, with covariance matrix parametrized as the sum of a diagonal matrix and a low-rank matrix

$\Sigma = D + W W^T$

The implementation is strongly inspired from Pytorch: https://github.com/pytorch/pytorch/blob/master/torch/distributions/lowrank_multivariate_normal.py.

Complexity to compute log_prob is $$O(dim * rank + rank^3)$$ per element.

Parameters
• dim – Dimension of the distribution’s support

• rank – Rank of W

• mu – Mean tensor, of shape (…, dim)

• D – Diagonal term in the covariance matrix, of shape (…, dim)

• W – Low-rank factor in the covariance matrix, of shape (…, dim, rank)

property F
arg_names = None
property batch_shape

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.

property 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 event_shape

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

Compute the log-density of the distribution at x.

Parameters

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

Returns

Tensor of shape batch_shape containing the log-density of the distribution for each event in x.

Return type

Tensor

property mean

Tensor containing the mean of the distribution.

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

Draw samples from the multivariate Gaussian distribution:

$s = \mu + D u + W v,$

where $$u$$ and $$v$$ are standard normal samples.

Parameters
• num_samples – number of samples to be drawn.

• dtype – Data-type of the samples.

Returns

Return type

tensor with shape (num_samples, .., dim)

property variance

Tensor containing the variance of the distribution.

class gluonts.mx.distribution.lowrank_multivariate_gaussian.LowrankMultivariateGaussianOutput(dim: int, rank: int, sigma_init: float = 1.0, sigma_minimum: float = 0.001)[source]
distr_cls = None
distribution(distr_args, loc=None, scale=None, **kwargs) → 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, mu_vector, D_vector, W_vector)[source]
Parameters
• F

• mu_vector – Tensor of shape (…, dim)

• D_vector – Tensor of shape (…, dim)

• W_vector – Tensor of shape (…, dim * rank )

Returns

A tuple containing tensors mu, D, and W, with shapes (…, dim), (…, dim), and (…, dim, rank), respectively.

Return type

Tuple

property event_shape

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]
gluonts.mx.distribution.lowrank_multivariate_gaussian.capacitance_tril(F, rank: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], W: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], D: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]
Parameters
• F

• rank

• W ((.., dim, rank)) –

• D ((.., dim)) –

Returns

Return type

the capacitance matrix $$I + W^T D^{-1} W$$

gluonts.mx.distribution.lowrank_multivariate_gaussian.inv_softplus(y)[source]
gluonts.mx.distribution.lowrank_multivariate_gaussian.log_det(F, batch_D: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], batch_capacitance_tril: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Uses the matrix determinant lemma.

$\log|D + W W^T| = \log|C| + \log|D|,$

where $$C$$ is the capacitance matrix $$I + W^T D^{-1} W$$, to compute the log determinant.

Parameters
• F

• batch_D

• batch_capacitance_tril

gluonts.mx.distribution.lowrank_multivariate_gaussian.lowrank_log_likelihood(rank: int, mu: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], D: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], W: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]
gluonts.mx.distribution.lowrank_multivariate_gaussian.mahalanobis_distance(F, W: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], D: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], capacitance_tril: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol], x: Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol]) → Union[mxnet.ndarray.ndarray.NDArray, mxnet.symbol.symbol.Symbol][source]

Uses the Woodbury matrix identity

$(W W^T + D)^{-1} = D^{-1} - D^{-1} W C^{-1} W^T D^{-1},$

where $$C$$ is the capacitance matrix $$I + W^T D^{-1} W$$, to compute the squared Mahalanobis distance $$x^T (W W^T + D)^{-1} x$$.

Parameters
• F

• W – (…, dim, rank)

• D – (…, dim)

• capacitance_tril – (…, rank, rank)

• x – (…, dim)