Implementation:Pyro ppl Pyro MultivariateStudentT

Knowledge Sources	Pyro
Domains	Probability_Distributions
Last Updated	2026-02-09 09:00 GMT

Overview

Description

MultivariateStudentT is a distribution class in Pyro implementing the multivariate Student's t-distribution. It is parameterized by three quantities: degrees of freedom (df), a location vector (loc), and a lower-triangular scale matrix (scale_tril) with positive diagonal entries (i.e., a Cholesky factor).

The class extends TorchDistribution and supports reparameterized sampling (has_rsample = True). Sampling is implemented using the standard representation of a multivariate t-distribution as a scaled mixture of normals: a standard normal vector is divided by the square root of a chi-squared random variable (scaled by degrees of freedom), then transformed via the Cholesky scale and shifted by the location.

The distribution provides several lazily-computed matrix properties:

• scale_tril - the broadcasted lower-triangular Cholesky factor
• covariance_matrix - computed as scale_tril @ scale_tril.T (note: the actual covariance is df / (df - 2) * covariance_matrix when df > 2)
• precision_matrix - the inverse of the covariance matrix, computed via Cholesky solve

The log_prob method computes the log probability density using the triangular solve of the Cholesky factor, avoiding explicit matrix inversion. The mean property returns loc when df > 1 (NaN otherwise), and the variance accounts for the degrees-of-freedom scaling, returning infinity when 1 < df <= 2 and NaN when df <= 1.

Full broadcasting is supported across df, loc, and scale_tril batch dimensions.

Usage

The multivariate Student's t-distribution is commonly used in Bayesian modeling as a robust alternative to the multivariate normal. Its heavier tails make it less sensitive to outliers. It is useful as both a prior distribution and a likelihood function in regression and hierarchical models. The degrees of freedom parameter controls the tail heaviness, with the distribution approaching a multivariate normal as df approaches infinity.

Code Reference

Source Location

• File: pyro/distributions/multivariate_studentt.py
• Repository: pyro-ppl/pyro

Signature

class MultivariateStudentT(TorchDistribution):
    def __init__(self, df, loc, scale_tril, validate_args=None)

Import

from pyro.distributions import MultivariateStudentT

I/O Contract

Inputs

Parameter	Type	Description
df	torch.Tensor or float	Degrees of freedom. Must be positive. Controls tail heaviness; lower values produce heavier tails.
loc	torch.Tensor	Mean (location) vector of the distribution. Shape determines the event dimension D via the last dimension.
scale_tril	torch.Tensor	Lower-triangular Cholesky factor of the scale matrix, of shape (..., D, D) with positive diagonal entries.
validate_args	bool or None	Whether to validate input arguments. Defaults to None.

Outputs

Method	Return Type	Description
rsample(sample_shape)	torch.Tensor	Returns a reparameterized sample of shape sample_shape + batch_shape + (D,).
log_prob(value)	torch.Tensor	Returns the log probability density of value with shape sample_shape + batch_shape.
mean	torch.Tensor	Returns the mean (loc) when df > 1, otherwise NaN.
variance	torch.Tensor	Returns the marginal variance vector, accounting for degrees of freedom scaling.
covariance_matrix	torch.Tensor	Returns the unscaled covariance matrix scale_tril @ scale_tril.T.
precision_matrix	torch.Tensor	Returns the precision (inverse covariance) matrix.

Usage Examples

import torch
from pyro.distributions import MultivariateStudentT

# Create a 3-dimensional multivariate Student's t with 5 degrees of freedom
df = 5.0
loc = torch.zeros(3)
scale_tril = torch.eye(3)

dist = MultivariateStudentT(df, loc, scale_tril)

# Draw a reparameterized sample
sample = dist.rsample()
print(sample.shape)  # torch.Size([3])

# Compute log probability
log_p = dist.log_prob(sample)
print(log_p.shape)  # torch.Size([])

# Access properties
print(dist.mean)              # tensor([0., 0., 0.])
print(dist.variance)          # tensor([1.6667, 1.6667, 1.6667])  (df/(df-2) = 5/3)
print(dist.covariance_matrix) # 3x3 identity

import pyro
import pyro.distributions as dist
import torch

# Using MultivariateStudentT as a robust likelihood
def model(data):
    loc = pyro.sample("loc", dist.Normal(torch.zeros(2), torch.ones(2)).to_event(1))
    df = pyro.sample("df", dist.Gamma(torch.tensor(2.0), torch.tensor(0.1)))
    scale_tril = torch.eye(2)

    with pyro.plate("obs", len(data)):
        pyro.sample("x", dist.MultivariateStudentT(df, loc, scale_tril), obs=data)

Related Pages

• Pyro_ppl_Pyro_OMTMultivariateNormal - Multivariate Normal with Optimal Transport gradients, a closely related multivariate distribution
• Pyro_ppl_Pyro_LKJ - LKJ distribution for correlation matrices, often used alongside multivariate distributions
• Pyro_ppl_Pyro_GaussianScaleMixture - Another multivariate distribution with structured covariance