Skip to content

← distributions package

TractableMultivariateNormalDistribution

Specify a tractable multivariate normal (aka Gaussian) distribution parameterized by a location mu, a diagonal vector D, and a tall low-rank factor U.

The resulting covariance or alternatively scale matrix of the distribution then is diag(D) + UU'. This parameterization is numerically stable in high dimensions. In either case the resulting distribution can capture the the dominant components of the covariance matrix without becoming singular due to the diagonal term, and is able to characterize the variance in any variables onto which the dominant components do not project. Note that the scale and cov parameterizations cannot easily be converted into each other, so you have to choose one and specify or estimate the parameters accordingly. More Info... Version 1.0.0

Ports/Properties

dist

The resulting distribution object.

  • verbose name: Dist
  • default value: None
  • port type: DataPort
  • value type: Distribution (can be None)
  • data direction: OUT

loc

Location vector.

  • verbose name: Location Vector (Mu)
  • default value: 0.0
  • port type: Port
  • value type: AnyNumeric (can be None)

diag

Diagonal of matrix, given as a vector.

  • verbose name: Diagonal Vector (D)
  • default value: [[1.0]]
  • port type: Port
  • value type: AnyNumeric (can be None)

factor

Additive factor of a low-rank term of size (M, k) where M is the dimensionality of the distribution and k is the rank of the low-rank term.

  • verbose name: Low-Rank Factor (U)
  • default value: [[0.0]]
  • port type: Port
  • value type: AnyNumeric (can be None)

form

Form of the parameterization. If set to cov, then D is a vector of variances, and cov = diag(D) + UU'. If set to scale, then diag is a vector of standard deviations, and the scale matrix is S = diag(D) + UU', and the covariance matrix is then cov = SS'. Note that not all backends support both parameterizations.

  • verbose name: Parameterization
  • default value: cov
  • port type: EnumPort
  • value type: str (can be None)

set_breakpoint

Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

  • verbose name: Set Breakpoint (Debug Only)
  • default value: False
  • port type: BoolPort
  • value type: bool (can be None)

metadata

User-definable meta-data associated with the node. Usually reserved for technical purposes.

  • verbose name: Metadata
  • default value: {}
  • port type: DictPort
  • value type: dict (can be None)

backend

Optional compute backend to use. Default is specific to the current context (e.g., as per WithBackend, DeepLearning, Inference nodes). All backends should return the same numbers to good numeric accuracy, although sampling will generally return different samples, and most backends support the most common distributions. For more esoteric distributions or their properties, scipy has the best coverage, followed by tfp, numpyro, torch, and distrax. All backends work on CPU, but performance can differ markedly between backends, even on CPU. Only the non-scipy backends work on the GPU. If you intend to take derivatives of expressions involving distributions, you will generally need to use one of the jax backends. If you are using the Inference nodes, the recommended backend is numpyro, but you may also try other jax-based backends. For use within pure deep learning, you also have to use jax backends, and distrax and numpyro are probably the best choices, followed by tfp due to the potentially lower speed. The torch backend is mainly useful within algorithms where the data is already on torch. If you aim to process batches of distributions (with different parameters), you must also use any of the non-scipy backends.

  • verbose name: Backend
  • default value: default
  • port type: EnumPort
  • value type: str (can be None)

axis_pairing

How to pair axes of the distribution parameter(s), if these parameters are specified with axes (e.g ., as blocks). In 'positional' mode, axes are paired by their position according to a right alignment, that is, the last axis of the first operand is paired with the last axis of the second operand, and so on, while any missing axes behave as if they were unnamed axes of length 1 (this is the same way plain n-dimensional arrays pair in Python/numpy). In 'matched' mode, axes are paired by their type and optionally label, where the axis order of the first operand is preserved in the output, optionally with additional axes that only occur in the subsequent operands prepended on the left. The other operands then have their axes reordered to match. In matched mode, the axes will also follow the order dictated by any ambient plate (With Stacked Variables) context if those contexts were set to pertain to an axis. All axis classes are treated as distinct, except for the plain axis, which is treated as a wildcard axis that can pair with any other axis. The 'default' value resolves to a value that may be overridden in special contexts (mainly the ambient Inference node) and otherwise resolves to the setting of the configuration variable default_axis_pairing, which is set to 'positional' in 2024.x. See also the 'label_handling' property for how labels are treated in this mode. Note that axis pairing can be subtle, and it is recommended to not blindly trust that the default behavior is always what the user intended.

  • verbose name: Axis Pairing
  • default value: default
  • port type: EnumPort
  • value type: str (can be None)

label_pairing

How to treat axis labels when pairing axes in 'matched' mode. In 'always' mode, labels are always considered significant, and axes with different labels are always considered distinct, which means that, if the two operands each have an axis of same type but with different labels, each operand will have a singleton axis inserted to pair with the respective axis in the other operand. In 'ignore' mode, labels are entirely ignored when pairing axes; this means that, if multiple axes of the same type occur in one or more operands, the last space axis in the first operand is paired with the last space axis in the second operand, etc. as in positional mode. In 'auto' mode, labels are only considered significant if they are necessary for distinguishing two or more axes of the same type in any of the operands, or if they occur on a plain axis.

  • verbose name: Label Pairing
  • default value: auto
  • port type: EnumPort
  • value type: str (can be None)