Distributions

Wraps torch.distributions.bernoulli.Bernoulli with TorchDistributionMixin.

Creates a Bernoulli distribution parameterized by probs or logits (but not both).

Samples are binary (0 or 1). They take the value 1 with probability p and 0 with probability 1 - p.

Example:

>>> m = Bernoulli(torch.tensor([0.3]))
>>> m.sample()  # 30% chance 1; 70% chance 0
tensor([ 0.])

Parameters

• probs (Number, Tensor) – the probability of sampling 1

• logits (Number, Tensor) – the log-odds of sampling 1

Wraps torch.distributions.beta.Beta with TorchDistributionMixin.

Beta distribution parameterized by concentration1 and concentration0.

Example:

>>> m = Beta(torch.tensor([0.5]), torch.tensor([0.5]))
>>> m.sample()  # Beta distributed with concentration concentration1 and concentration0
tensor([ 0.1046])

Parameters

• concentration1 (float or Tensor) – 1st concentration parameter of the distribution (often referred to as alpha)

• concentration0 (float or Tensor) – 2nd concentration parameter of the distribution (often referred to as beta)

Wraps torch.distributions.binomial.Binomial with TorchDistributionMixin.

Creates a Binomial distribution parameterized by total_count and either probs or logits (but not both). total_count must be broadcastable with probs/logits.

Example:

>>> m = Binomial(100, torch.tensor([0 , .2, .8, 1]))
>>> x = m.sample()
tensor([   0.,   22.,   71.,  100.])

>>> m = Binomial(torch.tensor([[5.], [10.]]), torch.tensor([0.5, 0.8]))
>>> x = m.sample()
tensor([[ 4.,  5.],
        [ 7.,  6.]])

Parameters

• total_count (int or Tensor) – number of Bernoulli trials

• probs (Tensor) – Event probabilities

• logits (Tensor) – Event log-odds

Wraps torch.distributions.categorical.Categorical with TorchDistributionMixin.

Creates a categorical distribution parameterized by either probs or logits (but not both).

Samples are integers from \(\{0, \ldots, K-1\}\) where K is probs.size(-1).

If probs is 1-dimensional with length-K, each element is the relative probability of sampling the class at that index.

If probs is N-dimensional, the first N-1 dimensions are treated as a batch of relative probability vectors.

See also: torch.multinomial()

Example:

>>> m = Categorical(torch.tensor([ 0.25, 0.25, 0.25, 0.25 ]))
>>> m.sample()  # equal probability of 0, 1, 2, 3
tensor(3)

Parameters

• probs (Tensor) – event probabilities

• logits (Tensor) – event log probabilities (unnormalized)

Wraps torch.distributions.cauchy.Cauchy with TorchDistributionMixin.

Samples from a Cauchy (Lorentz) distribution. The distribution of the ratio of independent normally distributed random variables with means 0 follows a Cauchy distribution.

Example:

>>> m = Cauchy(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Cauchy distribution with loc=0 and scale=1
tensor([ 2.3214])

Parameters

• loc (float or Tensor) – mode or median of the distribution.

• scale (float or Tensor) – half width at half maximum.

Wraps torch.distributions.chi2.Chi2 with TorchDistributionMixin.

Creates a Chi-squared distribution parameterized by shape parameter df. This is exactly equivalent to Gamma(alpha=0.5*df, beta=0.5)

Example:

>>> m = Chi2(torch.tensor([1.0]))
>>> m.sample()  # Chi2 distributed with shape df=1
tensor([ 0.1046])

Parameters

df (float or Tensor) – shape parameter of the distribution

Wraps torch.distributions.continuous_bernoulli.ContinuousBernoulli with TorchDistributionMixin.

Creates a continuous Bernoulli distribution parameterized by probs or logits (but not both).

The distribution is supported in [0, 1] and parameterized by ‘probs’ (in (0,1)) or ‘logits’ (real-valued). Note that, unlike the Bernoulli, ‘probs’ does not correspond to a probability and ‘logits’ does not correspond to log-odds, but the same names are used due to the similarity with the Bernoulli. See [1] for more details.

Example:

>>> m = ContinuousBernoulli(torch.tensor([0.3]))
>>> m.sample()
tensor([ 0.2538])

Parameters

• probs (Number, Tensor) – (0,1) valued parameters

• logits (Number, Tensor) – real valued parameters whose sigmoid matches ‘probs’

[1] The continuous Bernoulli: fixing a pervasive error in variational autoencoders, Loaiza-Ganem G and Cunningham JP, NeurIPS 2019. https://arxiv.org/abs/1907.06845

Wraps torch.distributions.dirichlet.Dirichlet with TorchDistributionMixin.

Creates a Dirichlet distribution parameterized by concentration concentration.

Example:

>>> m = Dirichlet(torch.tensor([0.5, 0.5]))
>>> m.sample()  # Dirichlet distributed with concentration [0.5, 0.5]
tensor([ 0.1046,  0.8954])

Parameters

concentration (Tensor) – concentration parameter of the distribution (often referred to as alpha)

Wraps torch.distributions.exponential.Exponential with TorchDistributionMixin.

Creates a Exponential distribution parameterized by rate.

Example:

>>> m = Exponential(torch.tensor([1.0]))
>>> m.sample()  # Exponential distributed with rate=1
tensor([ 0.1046])

Parameters

rate (float or Tensor) – rate = 1 / scale of the distribution

Wraps torch.distributions.exp_family.ExponentialFamily with TorchDistributionMixin.

ExponentialFamily is the abstract base class for probability distributions belonging to an exponential family, whose probability mass/density function has the form is defined below

where \(\theta\) denotes the natural parameters, \(t(x)\) denotes the sufficient statistic, \(F(\theta)\) is the log normalizer function for a given family and \(k(x)\) is the carrier measure.

Wraps torch.distributions.fishersnedecor.FisherSnedecor with TorchDistributionMixin.

Creates a Fisher-Snedecor distribution parameterized by df1 and df2.

Example:

>>> m = FisherSnedecor(torch.tensor([1.0]), torch.tensor([2.0]))
>>> m.sample()  # Fisher-Snedecor-distributed with df1=1 and df2=2
tensor([ 0.2453])

Parameters

• df1 (float or Tensor) – degrees of freedom parameter 1

• df2 (float or Tensor) – degrees of freedom parameter 2

Wraps torch.distributions.gamma.Gamma with TorchDistributionMixin.

Creates a Gamma distribution parameterized by shape concentration and rate.

Example:

>>> m = Gamma(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # Gamma distributed with concentration=1 and rate=1
tensor([ 0.1046])

Parameters

• concentration (float or Tensor) – shape parameter of the distribution (often referred to as alpha)

• rate (float or Tensor) – rate = 1 / scale of the distribution (often referred to as beta)

Wraps torch.distributions.geometric.Geometric with TorchDistributionMixin.

Creates a Geometric distribution parameterized by probs, where probs is the probability of success of Bernoulli trials. It represents the probability that in \(k + 1\) Bernoulli trials, the first \(k\) trials failed, before seeing a success.

Samples are non-negative integers [0, \(\inf\)).

Example:

>>> m = Geometric(torch.tensor([0.3]))
>>> m.sample()  # underlying Bernoulli has 30% chance 1; 70% chance 0
tensor([ 2.])

Parameters

• probs (Number, Tensor) – the probability of sampling 1. Must be in range (0, 1]

• logits (Number, Tensor) – the log-odds of sampling 1.

Wraps torch.distributions.gumbel.Gumbel with TorchDistributionMixin.

Samples from a Gumbel Distribution.

Examples:

>>> m = Gumbel(torch.tensor([1.0]), torch.tensor([2.0]))
>>> m.sample()  # sample from Gumbel distribution with loc=1, scale=2
tensor([ 1.0124])

Parameters

• loc (float or Tensor) – Location parameter of the distribution

• scale (float or Tensor) – Scale parameter of the distribution

Wraps torch.distributions.half_cauchy.HalfCauchy with TorchDistributionMixin.

Creates a half-Cauchy distribution parameterized by scale where:

X ~ Cauchy(0, scale)
Y = |X| ~ HalfCauchy(scale)

Example:

>>> m = HalfCauchy(torch.tensor([1.0]))
>>> m.sample()  # half-cauchy distributed with scale=1
tensor([ 2.3214])

Parameters

scale (float or Tensor) – scale of the full Cauchy distribution

Wraps torch.distributions.half_normal.HalfNormal with TorchDistributionMixin.

Creates a half-normal distribution parameterized by scale where:

X ~ Normal(0, scale)
Y = |X| ~ HalfNormal(scale)

Example:

>>> m = HalfNormal(torch.tensor([1.0]))
>>> m.sample()  # half-normal distributed with scale=1
tensor([ 0.1046])

Parameters

scale (float or Tensor) – scale of the full Normal distribution

Wraps torch.distributions.independent.Independent with TorchDistributionMixin.

Reinterprets some of the batch dims of a distribution as event dims.

This is mainly useful for changing the shape of the result of log_prob(). For example to create a diagonal Normal distribution with the same shape as a Multivariate Normal distribution (so they are interchangeable), you can:

>>> from torch.distributions.multivariate_normal import MultivariateNormal
>>> from torch.distributions.normal import Normal
>>> loc = torch.zeros(3)
>>> scale = torch.ones(3)
>>> mvn = MultivariateNormal(loc, scale_tril=torch.diag(scale))
>>> [mvn.batch_shape, mvn.event_shape]
[torch.Size([]), torch.Size([3])]
>>> normal = Normal(loc, scale)
>>> [normal.batch_shape, normal.event_shape]
[torch.Size([3]), torch.Size([])]
>>> diagn = Independent(normal, 1)
>>> [diagn.batch_shape, diagn.event_shape]
[torch.Size([]), torch.Size([3])]

Parameters

• base_distribution (torch.distributions.distribution.Distribution) – a base distribution

• reinterpreted_batch_ndims (int) – the number of batch dims to reinterpret as event dims

Wraps torch.distributions.kumaraswamy.Kumaraswamy with TorchDistributionMixin.

Samples from a Kumaraswamy distribution.

Example:

>>> m = Kumaraswamy(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Kumaraswamy distribution with concentration alpha=1 and beta=1
tensor([ 0.1729])

Parameters

• concentration1 (float or Tensor) – 1st concentration parameter of the distribution (often referred to as alpha)

• concentration0 (float or Tensor) – 2nd concentration parameter of the distribution (often referred to as beta)

Wraps torch.distributions.lkj_cholesky.LKJCholesky with TorchDistributionMixin.

LKJ distribution for lower Cholesky factor of correlation matrices. The distribution is controlled by concentration parameter \(\eta\) to make the probability of the correlation matrix \(M\) generated from a Cholesky factor proportional to \(\det(M)^{\eta - 1}\). Because of that, when concentration == 1, we have a uniform distribution over Cholesky factors of correlation matrices:

L ~ LKJCholesky(dim, concentration)
X = L @ L' ~ LKJCorr(dim, concentration)

Note that this distribution samples the Cholesky factor of correlation matrices and not the correlation matrices themselves and thereby differs slightly from the derivations in [1] for the LKJCorr distribution. For sampling, this uses the Onion method from [1] Section 3.

Example:

>>> l = LKJCholesky(3, 0.5)
>>> l.sample()  # l @ l.T is a sample of a correlation 3x3 matrix
tensor([[ 1.0000,  0.0000,  0.0000],
        [ 0.3516,  0.9361,  0.0000],
        [-0.1899,  0.4748,  0.8593]])

Parameters

• dimension (dim) – dimension of the matrices

• concentration (float or Tensor) – concentration/shape parameter of the distribution (often referred to as eta)

References

[1] Generating random correlation matrices based on vines and extended onion method (2009), Daniel Lewandowski, Dorota Kurowicka, Harry Joe. Journal of Multivariate Analysis. 100. 10.1016/j.jmva.2009.04.008

Wraps torch.distributions.laplace.Laplace with TorchDistributionMixin.

Creates a Laplace distribution parameterized by loc and scale.

Example:

>>> m = Laplace(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # Laplace distributed with loc=0, scale=1
tensor([ 0.1046])

Parameters

• loc (float or Tensor) – mean of the distribution

• scale (float or Tensor) – scale of the distribution

Wraps torch.distributions.log_normal.LogNormal with TorchDistributionMixin.

Creates a log-normal distribution parameterized by loc and scale where:

X ~ Normal(loc, scale)
Y = exp(X) ~ LogNormal(loc, scale)

Example:

>>> m = LogNormal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # log-normal distributed with mean=0 and stddev=1
tensor([ 0.1046])

Parameters

• loc (float or Tensor) – mean of log of distribution

• scale (float or Tensor) – standard deviation of log of the distribution

Wraps torch.distributions.logistic_normal.LogisticNormal with TorchDistributionMixin.

Creates a logistic-normal distribution parameterized by loc and scale that define the base Normal distribution transformed with the StickBreakingTransform such that:

X ~ LogisticNormal(loc, scale)
Y = log(X / (1 - X.cumsum(-1)))[..., :-1] ~ Normal(loc, scale)

Parameters

• loc (float or Tensor) – mean of the base distribution

• scale (float or Tensor) – standard deviation of the base distribution

Example:

>>> # logistic-normal distributed with mean=(0, 0, 0) and stddev=(1, 1, 1)
>>> # of the base Normal distribution
>>> m = LogisticNormal(torch.tensor([0.0] * 3), torch.tensor([1.0] * 3))
>>> m.sample()
tensor([ 0.7653,  0.0341,  0.0579,  0.1427])

Wraps torch.distributions.lowrank_multivariate_normal.LowRankMultivariateNormal with TorchDistributionMixin.

Creates a multivariate normal distribution with covariance matrix having a low-rank form parameterized by cov_factor and cov_diag:

covariance_matrix = cov_factor @ cov_factor.T + cov_diag

Example

>>> m = LowRankMultivariateNormal(torch.zeros(2), torch.tensor([[1.], [0.]]), torch.ones(2))
>>> m.sample()  # normally distributed with mean=`[0,0]`, cov_factor=`[[1],[0]]`, cov_diag=`[1,1]`
tensor([-0.2102, -0.5429])

Parameters

• loc (Tensor) – mean of the distribution with shape batch_shape + event_shape

• cov_factor (Tensor) – factor part of low-rank form of covariance matrix with shape batch_shape + event_shape + (rank,)

• cov_diag (Tensor) – diagonal part of low-rank form of covariance matrix with shape batch_shape + event_shape

capacitance = I + cov_factor.T @ inv(cov_diag) @ cov_factor

Wraps torch.distributions.mixture_same_family.MixtureSameFamily with TorchDistributionMixin.

The MixtureSameFamily distribution implements a (batch of) mixture distribution where all component are from different parameterizations of the same distribution type. It is parameterized by a Categorical “selecting distribution” (over k component) and a component distribution, i.e., a Distribution with a rightmost batch shape (equal to [k]) which indexes each (batch of) component.

Examples:

>>> # Construct Gaussian Mixture Model in 1D consisting of 5 equally
>>> # weighted normal distributions
>>> mix = D.Categorical(torch.ones(5,))
>>> comp = D.Normal(torch.randn(5,), torch.rand(5,))
>>> gmm = MixtureSameFamily(mix, comp)

>>> # Construct Gaussian Mixture Modle in 2D consisting of 5 equally
>>> # weighted bivariate normal distributions
>>> mix = D.Categorical(torch.ones(5,))
>>> comp = D.Independent(D.Normal(
...          torch.randn(5,2), torch.rand(5,2)), 1)
>>> gmm = MixtureSameFamily(mix, comp)

>>> # Construct a batch of 3 Gaussian Mixture Models in 2D each
>>> # consisting of 5 random weighted bivariate normal distributions
>>> mix = D.Categorical(torch.rand(3,5))
>>> comp = D.Independent(D.Normal(
...         torch.randn(3,5,2), torch.rand(3,5,2)), 1)
>>> gmm = MixtureSameFamily(mix, comp)

Parameters

• mixture_distribution – torch.distributions.Categorical-like instance. Manages the probability of selecting component. The number of categories must match the rightmost batch dimension of the component_distribution. Must have either scalar batch_shape or batch_shape matching component_distribution.batch_shape[:-1]

• component_distribution – torch.distributions.Distribution-like instance. Right-most batch dimension indexes component.

Wraps torch.distributions.multinomial.Multinomial with TorchDistributionMixin.

Creates a Multinomial distribution parameterized by total_count and either probs or logits (but not both). The innermost dimension of probs indexes over categories. All other dimensions index over batches.

Note that total_count need not be specified if only log_prob() is called (see example below)

• sample() requires a single shared total_count for all parameters and samples.

• log_prob() allows different total_count for each parameter and sample.

Example:

>>> m = Multinomial(100, torch.tensor([ 1., 1., 1., 1.]))
>>> x = m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 21.,  24.,  30.,  25.])

>>> Multinomial(probs=torch.tensor([1., 1., 1., 1.])).log_prob(x)
tensor([-4.1338])

Parameters

• total_count (int) – number of trials

• probs (Tensor) – event probabilities

• logits (Tensor) – event log probabilities (unnormalized)

Wraps torch.distributions.multivariate_normal.MultivariateNormal with TorchDistributionMixin.

Creates a multivariate normal (also called Gaussian) distribution parameterized by a mean vector and a covariance matrix.

The multivariate normal distribution can be parameterized either in terms of a positive definite covariance matrix \(\mathbf{\Sigma}\) or a positive definite precision matrix \(\mathbf{\Sigma}^{-1}\) or a lower-triangular matrix \(\mathbf{L}\) with positive-valued diagonal entries, such that \(\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top\). This triangular matrix can be obtained via e.g. Cholesky decomposition of the covariance.

Example

>>> m = MultivariateNormal(torch.zeros(2), torch.eye(2))
>>> m.sample()  # normally distributed with mean=`[0,0]` and covariance_matrix=`I`
tensor([-0.2102, -0.5429])

Parameters

• loc (Tensor) – mean of the distribution

• covariance_matrix (Tensor) – positive-definite covariance matrix

• precision_matrix (Tensor) – positive-definite precision matrix

• scale_tril (Tensor) – lower-triangular factor of covariance, with positive-valued diagonal

Wraps torch.distributions.negative_binomial.NegativeBinomial with TorchDistributionMixin.

Creates a Negative Binomial distribution, i.e. distribution of the number of successful independent and identical Bernoulli trials before total_count failures are achieved. The probability of success of each Bernoulli trial is probs.

Parameters

• total_count (float or Tensor) – non-negative number of negative Bernoulli trials to stop, although the distribution is still valid for real valued count

• probs (Tensor) – Event probabilities of success in the half open interval [0, 1)

• logits (Tensor) – Event log-odds for probabilities of success

Wraps torch.distributions.normal.Normal with TorchDistributionMixin.

Creates a normal (also called Gaussian) distribution parameterized by loc and scale.

Example:

>>> m = Normal(torch.tensor([0.0]), torch.tensor([1.0]))
>>> m.sample()  # normally distributed with loc=0 and scale=1
tensor([ 0.1046])

Parameters

• loc (float or Tensor) – mean of the distribution (often referred to as mu)

• scale (float or Tensor) – standard deviation of the distribution (often referred to as sigma)

Wraps torch.distributions.one_hot_categorical.OneHotCategorical with TorchDistributionMixin.

Creates a one-hot categorical distribution parameterized by probs or logits.

Samples are one-hot coded vectors of size probs.size(-1).

See also: torch.distributions.Categorical() for specifications of probs and logits.

Example:

>>> m = OneHotCategorical(torch.tensor([ 0.25, 0.25, 0.25, 0.25 ]))
>>> m.sample()  # equal probability of 0, 1, 2, 3
tensor([ 0.,  0.,  0.,  1.])

Parameters

• probs (Tensor) – event probabilities

• logits (Tensor) – event log probabilities (unnormalized)

Wraps torch.distributions.one_hot_categorical.OneHotCategoricalStraightThrough with TorchDistributionMixin.

Creates a reparameterizable OneHotCategorical distribution based on the straight- through gradient estimator from [1].

[1] Estimating or Propagating Gradients Through Stochastic Neurons for Conditional Computation (Bengio et al, 2013)

Wraps torch.distributions.pareto.Pareto with TorchDistributionMixin.

Samples from a Pareto Type 1 distribution.

Example:

>>> m = Pareto(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Pareto distribution with scale=1 and alpha=1
tensor([ 1.5623])

Parameters

• scale (float or Tensor) – Scale parameter of the distribution

• alpha (float or Tensor) – Shape parameter of the distribution

Wraps torch.distributions.poisson.Poisson with TorchDistributionMixin.

Creates a Poisson distribution parameterized by rate, the rate parameter.

Samples are nonnegative integers, with a pmf given by

Example:

>>> m = Poisson(torch.tensor([4]))
>>> m.sample()
tensor([ 3.])

Parameters

rate (Number, Tensor) – the rate parameter

Wraps torch.distributions.relaxed_bernoulli.RelaxedBernoulli with TorchDistributionMixin.

Creates a RelaxedBernoulli distribution, parametrized by temperature, and either probs or logits (but not both). This is a relaxed version of the Bernoulli distribution, so the values are in (0, 1), and has reparametrizable samples.

Example:

>>> m = RelaxedBernoulli(torch.tensor([2.2]),
...                      torch.tensor([0.1, 0.2, 0.3, 0.99]))
>>> m.sample()
tensor([ 0.2951,  0.3442,  0.8918,  0.9021])

Parameters

• temperature (Tensor) – relaxation temperature

• probs (Number, Tensor) – the probability of sampling 1

• logits (Number, Tensor) – the log-odds of sampling 1

Wraps torch.distributions.relaxed_categorical.RelaxedOneHotCategorical with TorchDistributionMixin.

Creates a RelaxedOneHotCategorical distribution parametrized by temperature, and either probs or logits. This is a relaxed version of the OneHotCategorical distribution, so its samples are on simplex, and are reparametrizable.

Example:

>>> m = RelaxedOneHotCategorical(torch.tensor([2.2]),
...                              torch.tensor([0.1, 0.2, 0.3, 0.4]))
>>> m.sample()
tensor([ 0.1294,  0.2324,  0.3859,  0.2523])

Parameters

• temperature (Tensor) – relaxation temperature

• probs (Tensor) – event probabilities

• logits (Tensor) – unnormalized log probability for each event

Wraps torch.distributions.studentT.StudentT with TorchDistributionMixin.

Creates a Student’s t-distribution parameterized by degree of freedom df, mean loc and scale scale.

Example:

>>> m = StudentT(torch.tensor([2.0]))
>>> m.sample()  # Student's t-distributed with degrees of freedom=2
tensor([ 0.1046])

Parameters

• df (float or Tensor) – degrees of freedom

• loc (float or Tensor) – mean of the distribution

• scale (float or Tensor) – scale of the distribution

Wraps torch.distributions.transformed_distribution.TransformedDistribution with TorchDistributionMixin.

Extension of the Distribution class, which applies a sequence of Transforms to a base distribution. Let f be the composition of transforms applied:

X ~ BaseDistribution
Y = f(X) ~ TransformedDistribution(BaseDistribution, f)
log p(Y) = log p(X) + log |det (dX/dY)|

Note that the .event_shape of a TransformedDistribution is the maximum shape of its base distribution and its transforms, since transforms can introduce correlations among events.

An example for the usage of TransformedDistribution would be:

# Building a Logistic Distribution
# X ~ Uniform(0, 1)
# f = a + b * logit(X)
# Y ~ f(X) ~ Logistic(a, b)
base_distribution = Uniform(0, 1)
transforms = [SigmoidTransform().inv, AffineTransform(loc=a, scale=b)]
logistic = TransformedDistribution(base_distribution, transforms)

For more examples, please look at the implementations of Gumbel, HalfCauchy, HalfNormal, LogNormal, Pareto, Weibull, RelaxedBernoulli and RelaxedOneHotCategorical

Wraps torch.distributions.uniform.Uniform with TorchDistributionMixin.

Generates uniformly distributed random samples from the half-open interval [low, high).

Example:

>>> m = Uniform(torch.tensor([0.0]), torch.tensor([5.0]))
>>> m.sample()  # uniformly distributed in the range [0.0, 5.0)
tensor([ 2.3418])

Parameters

• low (float or Tensor) – lower range (inclusive).

• high (float or Tensor) – upper range (exclusive).

Wraps torch.distributions.von_mises.VonMises with TorchDistributionMixin.

A circular von Mises distribution.

This implementation uses polar coordinates. The loc and value args can be any real number (to facilitate unconstrained optimization), but are interpreted as angles modulo 2 pi.

Example::

>>> m = VonMises(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # von Mises distributed with loc=1 and concentration=1
tensor([1.9777])

Parameters

• loc (torch.Tensor) – an angle in radians.

• concentration (torch.Tensor) – concentration parameter

Wraps torch.distributions.weibull.Weibull with TorchDistributionMixin.

Samples from a two-parameter Weibull distribution.

Example

>>> m = Weibull(torch.tensor([1.0]), torch.tensor([1.0]))
>>> m.sample()  # sample from a Weibull distribution with scale=1, concentration=1
tensor([ 0.4784])

Parameters

• scale (float or Tensor) – Scale parameter of distribution (lambda).

• concentration (float or Tensor) – Concentration parameter of distribution (k/shape).

Wraps torch.distributions.wishart.Wishart with TorchDistributionMixin.

Creates a Wishart distribution parameterized by a symmetric positive definite matrix \(\Sigma\), or its Cholesky decomposition \(\mathbf{\Sigma} = \mathbf{L}\mathbf{L}^\top\)

Example

>>> m = Wishart(torch.eye(2), torch.Tensor([2]))
>>> m.sample()  # Wishart distributed with mean=`df * I` and
>>>             # variance(x_ij)=`df` for i != j and variance(x_ij)=`2 * df` for i == j

Parameters

• covariance_matrix (Tensor) – positive-definite covariance matrix

• precision_matrix (Tensor) – positive-definite precision matrix

• scale_tril (Tensor) – lower-triangular factor of covariance, with positive-valued diagonal

• df (float or Tensor) – real-valued parameter larger than the (dimension of Square matrix) - 1

References

[1] Wang, Z., Wu, Y. and Chu, H., 2018. On equivalence of the LKJ distribution and the restricted Wishart distribution. [2] Sawyer, S., 2007. Wishart Distributions and Inverse-Wishart Sampling. [3] Anderson, T. W., 2003. An Introduction to Multivariate Statistical Analysis (3rd ed.). [4] Odell, P. L. & Feiveson, A. H., 1966. A Numerical Procedure to Generate a SampleCovariance Matrix. JASA, 61(313):199-203. [5] Ku, Y.-C. & Bloomfield, P., 2010. Generating Random Wishart Matrices with Fractional Degrees of Freedom in OX.

Bases: object

Base class for parameterized probability distributions.

Distributions in Pyro are stochastic function objects with sample() and log_prob() methods. Distribution are stochastic functions with fixed parameters:

d = dist.Bernoulli(param)
x = d()                                # Draws a random sample.
p = d.log_prob(x)                      # Evaluates log probability of x.

Implementing New Distributions:

Derived classes must implement the methods: sample(), log_prob().

Examples:

Take a look at the examples to see how they interact with inference algorithms.

has_rsample = False

has_enumerate_support = False

__call__(*args, **kwargs)[source]

Samples a random value (just an alias for .sample(*args, **kwargs)).

For tensor distributions, the returned tensor should have the same .shape as the parameters.

Returns

A random value.

Return type

torch.Tensor

abstract sample(*args, **kwargs)[source]

Samples a random value.

For tensor distributions, the returned tensor should have the same .shape as the parameters, unless otherwise noted.

Parameters

sample_shape (torch.Size) – the size of the iid batch to be drawn from the distribution.

Returns

A random value or batch of random values (if parameters are batched). The shape of the result should be self.shape().

Return type

torch.Tensor

abstract log_prob(x, *args, **kwargs)[source]

Evaluates log probability densities for each of a batch of samples.

Parameters

x (torch.Tensor) – A single value or a batch of values batched along axis 0.

Returns

log probability densities as a one-dimensional Tensor with same batch size as value and params. The shape of the result should be self.batch_size.

Return type

torch.Tensor

score_parts(x, *args, **kwargs)[source]

Computes ingredients for stochastic gradient estimators of ELBO.

The default implementation is correct both for non-reparameterized and for fully reparameterized distributions. Partially reparameterized distributions should override this method to compute correct .score_function and .entropy_term parts.

Setting .has_rsample on a distribution instance will determine whether inference engines like SVI use reparameterized samplers or the score function estimator.

Parameters

x (torch.Tensor) – A single value or batch of values.

Returns

A ScoreParts object containing parts of the ELBO estimator.

Return type

ScoreParts

enumerate_support(expand: bool = True) → torch.Tensor[source]

Returns a representation of the parametrized distribution’s support, along the first dimension. This is implemented only by discrete distributions.

Note that this returns support values of all the batched RVs in lock-step, rather than the full cartesian product.

Parameters

expand (bool) – whether to expand the result to a tensor of shape (n,) + batch_shape + event_shape. If false, the return value has unexpanded shape (n,) + (1,)*len(batch_shape) + event_shape which can be broadcasted to the full shape.

Returns

An iterator over the distribution’s discrete support.

Return type

iterator

conjugate_update(other)[source]

EXPERIMENTAL Creates an updated distribution fusing information from another compatible distribution. This is supported by only a few conjugate distributions.

This should satisfy the equation:

fg, log_normalizer = f.conjugate_update(g)
assert f.log_prob(x) + g.log_prob(x) == fg.log_prob(x) + log_normalizer

Note this is equivalent to funsor.ops.add on Funsor distributions, but we return a lazy sum (updated, log_normalizer) because PyTorch distributions must be normalized. Thus conjugate_update() should commute with dist_to_funsor() and tensor_to_funsor()

dist_to_funsor(f) + dist_to_funsor(g)
  == dist_to_funsor(fg) + tensor_to_funsor(log_normalizer)

Parameters

other – A distribution representing p(data|latent) but normalized over latent rather than data. Here latent is a candidate sample from self and data is a ground observation of unrelated type.

Returns

a pair (updated,log_normalizer) where updated is an updated distribution of type type(self), and log_normalizer is a Tensor representing the normalization factor.

has_rsample_(value)[source]

Force reparameterized or detached sampling on a single distribution instance. This sets the .has_rsample attribute in-place.

This is useful to instruct inference algorithms to avoid reparameterized gradients for variables that discontinuously determine downstream control flow.

Parameters

value (bool) – Whether samples will be pathwise differentiable.

Returns

self

Return type

Distribution

property rv

EXPERIMENTAL Switch to the Random Variable DSL for applying transformations to random variables. Supports either chaining operations or arithmetic operator overloading.

Example usage:

# This should be equivalent to an Exponential distribution.
Uniform(0, 1).rv.log().neg().dist

# These two distributions Y1, Y2 should be the same
X = Uniform(0, 1).rv
Y1 = X.mul(4).pow(0.5).sub(1).abs().neg().dist
Y2 = (-abs((4*X)**(0.5) - 1)).dist

Returns

A :class: ~pyro.contrib.randomvariable.random_variable.RandomVariable object wrapping this distribution.

Return type

RandomVariable

Bases: pyro.distributions.distribution.Distribution, Callable

Mixin to provide Pyro compatibility for PyTorch distributions.

You should instead use TorchDistribution for new distribution classes.

This is mainly useful for wrapping existing PyTorch distributions for use in Pyro. Derived classes must first inherit from torch.distributions.distribution.Distribution and then inherit from TorchDistributionMixin.

__call__(sample_shape: torch.Size = torch.Size([])) → torch.Tensor[source]

Samples a random value.

This is reparameterized whenever possible, calling rsample() for reparameterized distributions and sample() for non-reparameterized distributions.

Parameters

sample_shape (torch.Size) – the size of the iid batch to be drawn from the distribution.

Returns

A random value or batch of random values (if parameters are batched). The shape of the result should be self.shape().

Return type

torch.Tensor

property batch_shape: torch.Size

The shape over which parameters are batched. :rtype: torch.Size

Type

return

property event_shape: torch.Size

The shape of a single sample from the distribution (without batching). :rtype: torch.Size

Type

return

property event_dim: int

Number of dimensions of individual events. :rtype: int

Type

return

shape(sample_shape=torch.Size([]))[source]

The tensor shape of samples from this distribution.

Samples are of shape:

d.shape(sample_shape) == sample_shape + d.batch_shape + d.event_shape

Parameters

sample_shape (torch.Size) – the size of the iid batch to be drawn from the distribution.

Returns

Tensor shape of samples.

Return type

torch.Size

classmethod infer_shapes(**arg_shapes)[source]

Infers batch_shape and event_shape given shapes of args to __init__().

Note

This assumes distribution shape depends only on the shapes of tensor inputs, not in the data contained in those inputs.

Parameters

**arg_shapes – Keywords mapping name of input arg to torch.Size or tuple representing the sizes of each tensor input.

Returns

A pair (batch_shape, event_shape) of the shapes of a distribution that would be created with input args of the given shapes.

Return type

tuple

expand(batch_shape, _instance=None) → pyro.distributions.torch_distribution.ExpandedDistribution[source]

Returns a new ExpandedDistribution instance with batch dimensions expanded to batch_shape.

Parameters

• batch_shape (tuple) – batch shape to expand to.

• _instance – unused argument for compatibility with torch.distributions.Distribution.expand()

Returns

an instance of ExpandedDistribution.

Return type

ExpandedDistribution

expand_by(sample_shape)[source]

Expands a distribution by adding sample_shape to the left side of its batch_shape.

To expand internal dims of self.batch_shape from 1 to something larger, use expand() instead.

Parameters

sample_shape (torch.Size) – The size of the iid batch to be drawn from the distribution.

Returns

An expanded version of this distribution.

Return type

ExpandedDistribution

reshape(sample_shape=None, extra_event_dims=None)[source]

to_event(reinterpreted_batch_ndims=None)[source]

Reinterprets the n rightmost dimensions of this distributions batch_shape as event dims, adding them to the left side of event_shape.

Example

>>> [d1.batch_shape, d1.event_shape]
[torch.Size([2, 3]), torch.Size([4, 5])]
>>> d2 = d1.to_event(1)
>>> [d2.batch_shape, d2.event_shape]
[torch.Size([2]), torch.Size([3, 4, 5])]
>>> d3 = d1.to_event(2)
>>> [d3.batch_shape, d3.event_shape]
[torch.Size([]), torch.Size([2, 3, 4, 5])]

Parameters

reinterpreted_batch_ndims (int) – The number of batch dimensions to reinterpret as event dimensions. May be negative to remove dimensions from an pyro.distributions.torch.Independent . If None, convert all dimensions to event dimensions.

Returns

A reshaped version of this distribution.

Return type

pyro.distributions.torch.Independent

independent(reinterpreted_batch_ndims=None)[source]

mask(mask)[source]

Masks a distribution by a boolean or boolean-valued tensor that is broadcastable to the distributions batch_shape .

Parameters

mask (bool or torch.Tensor) – A boolean or boolean valued tensor.

Returns

A masked copy of this distribution.

Return type

MaskedDistribution

Bases: pyro.distributions.distribution.Distribution, Callable

Base class for PyTorch-compatible distributions with Pyro support.

This should be the base class for almost all new Pyro distributions.

Tensor Shapes:

TorchDistributions provide a method .shape() for the tensor shape of samples:

x = d.sample(sample_shape)
assert x.shape == d.shape(sample_shape)

Pyro follows the same distribution shape semantics as PyTorch. It distinguishes between three different roles for tensor shapes of samples:

• sample shape corresponds to the shape of the iid samples drawn from the distribution. This is taken as an argument by the distribution’s sample method.

• batch shape corresponds to non-identical (independent) parameterizations of the distribution, inferred from the distribution’s parameter shapes. This is fixed for a distribution instance.

• event shape corresponds to the event dimensions of the distribution, which is fixed for a distribution class. These are collapsed when we try to score a sample from the distribution via d.log_prob(x).

These shapes are related by the equation:

assert d.shape(sample_shape) == sample_shape + d.batch_shape + d.event_shape

Distributions provide a vectorized log_prob() method that evaluates the log probability density of each event in a batch independently, returning a tensor of shape sample_shape + d.batch_shape:

x = d.sample(sample_shape)
assert x.shape == d.shape(sample_shape)
log_p = d.log_prob(x)
assert log_p.shape == sample_shape + d.batch_shape

Implementing New Distributions:

Derived classes must implement the methods sample() (or rsample() if .has_rsample == True) and log_prob(), and must implement the properties batch_shape, and event_shape. Discrete classes may also implement the enumerate_support() method to improve gradient estimates and set .has_enumerate_support = True.

expand(batch_shape, _instance=None) → pyro.distributions.torch_distribution.ExpandedDistribution

Returns a new ExpandedDistribution instance with batch dimensions expanded to batch_shape.

Parameters

• batch_shape (tuple) – batch shape to expand to.

• _instance – unused argument for compatibility with torch.distributions.Distribution.expand()

Returns

an instance of ExpandedDistribution.

Return type

ExpandedDistribution

Bases: pyro.distributions.distribution.Distribution, Callable

Beta distribution scaled by scale and shifted by loc:

X ~ Beta(concentration1, concentration0)
f(X) = loc + scale * X
Y = f(X) ~ AffineBeta(concentration1, concentration0, loc, scale)

Parameters

• concentration1 (float or torch.Tensor) – 1st concentration parameter (alpha) for the Beta distribution.

• concentration0 (float or torch.Tensor) – 2nd concentration parameter (beta) for the Beta distribution.

• loc (float or torch.Tensor) – location parameter.

• scale (float or torch.Tensor) – scale parameter.

arg_constraints: Dict[str, torch.distributions.constraints.Constraint] = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0), 'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

property concentration0

property concentration1

expand(batch_shape, _instance=None)[source]

property high

static infer_shapes(concentration1, concentration0, loc, scale)[source]

property loc

property low

property mean

rsample(sample_shape=torch.Size([]))[source]

Generates a sample from Beta distribution and applies AffineTransform. Additionally clamps the output in order to avoid NaN and Inf values in the gradients.

sample(sample_shape=torch.Size([]))[source]

Generates a sample from Beta distribution and applies AffineTransform. Additionally clamps the output in order to avoid NaN and Inf values in the gradients.

property sample_size

property scale

property support

property variance

Bases: pyro.distributions.distribution.Distribution, Callable

Asymmetric version of the Laplace distribution.

To the left of loc this acts like an -Exponential(1/(asymmetry*scale)); to the right of loc this acts like an Exponential(asymmetry/scale). The density is continuous so the left and right densities at loc agree.

Parameters

• loc – Location parameter, i.e. the mode.

• scale – Scale parameter = geometric mean of left and right scales.

• asymmetry – Square of ratio of left to right scales.

arg_constraints = {'asymmetry': GreaterThan(lower_bound=0.0), 'loc': Real(), 'scale': GreaterThan(lower_bound=0.0)}

expand(batch_shape, _instance=None)[source]

has_rsample = True

property left_scale

log_prob(value)[source]

property mean

property right_scale

rsample(sample_shape=torch.Size([]))[source]

support = Real()

property variance

Bases: pyro.distributions.distribution.Distribution, Callable

Multivariate normal (Gaussian) distribution with transport equation inspired control variates (adaptive velocity fields).

A distribution over vectors in which all the elements have a joint Gaussian density.

Parameters

• loc (torch.Tensor) – D-dimensional mean vector.

• scale_tril (torch.Tensor) – Cholesky of Covariance matrix; D x D matrix.

• control_var (torch.Tensor) – 2 x L x D tensor that parameterizes the control variate; L is an arbitrary positive integer. This parameter needs to be learned (i.e. adapted) to achieve lower variance gradients. In a typical use case this parameter will be adapted concurrently with the loc and scale_tril that define the distribution.

Example usage:

control_var = torch.tensor(0.1 * torch.ones(2, 1, D), requires_grad=True)
opt_cv = torch.optim.Adam([control_var], lr=0.1, betas=(0.5, 0.999))

for _ in range(1000):
    d = AVFMultivariateNormal(loc, scale_tril, control_var)
    z = d.rsample()
    cost = torch.pow(z, 2.0).sum()
    cost.backward()
    opt_cv.step()
    opt_cv.zero_grad()

arg_constraints = {'control_var': Real(), 'loc': Real(), 'scale_tril': LowerTriangular()}

rsample(sample_shape=torch.Size([]))[source]

Bases: pyro.distributions.distribution.Distribution, Callable

Compound distribution comprising of a beta-binomial pair. The probability of success (probs for the Binomial distribution) is unknown and randomly drawn from a Beta distribution prior to a certain number of Bernoulli trials given by total_count.

Parameters

• concentration1 (float or torch.Tensor) – 1st concentration parameter (alpha) for the Beta distribution.

• concentration0 (float or torch.Tensor) – 2nd concentration parameter (beta) for the Beta distribution.

• total_count (float or torch.Tensor) – Number of Bernoulli trials.

approx_log_prob_tol = 0.0

arg_constraints = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0), 'total_count': IntegerGreaterThan(lower_bound=0)}

property concentration0

property concentration1

enumerate_support(expand=True)[source]

expand(batch_shape, _instance=None)[source]

has_enumerate_support = True

log_prob(value)[source]

property mean

sample(sample_shape=())[source]

property support

property variance

Bases: pyro.distributions.distribution.Distribution, Callable

Distribution over sorted coalescent times given irregular sampled leaf_times and constant population size.

Sample values will be sorted sets of binary coalescent times. Each sample value will have cardinality value.size(-1) = leaf_times.size(-1) - 1, so that phylogenies are complete binary trees. This distribution can thus be batched over multiple samples of phylogenies given fixed (number of) leaf times, e.g. over phylogeny samples from BEAST or MrBayes.

References

[1] J.F.C. Kingman (1982)

“On the Genealogy of Large Populations” Journal of Applied Probability

[2] J.F.C. Kingman (1982)

“The Coalescent” Stochastic Processes and their Applications

Parameters

• leaf_times (torch.Tensor) – Vector of times of sampling events, i.e. leaf nodes in the phylogeny. These can be arbitrary real numbers with arbitrary order and duplicates.

• rate (torch.Tensor) – Base coalescent rate (pairwise rate of coalescence) under a constant population size model. Defaults to 1.

arg_constraints = {'leaf_times': Real(), 'rate': GreaterThan(lower_bound=0.0)}

log_prob(value)[source]

sample(sample_shape=torch.Size([]))[source]

property support

Bases: pyro.distributions.distribution.Distribution, Callable

Distribution over coalescent times given irregular sampled leaf_times and piecewise constant coalescent rates defined on a regular time grid.

This assumes a piecewise constant base coalescent rate specified on time intervals (-inf,1], [1,2], …, [T-1,inf), where T = rate_grid.size(-1). Leaves may be sampled at arbitrary real times, but are commonly sampled in the interval [0, T].

Sample values will be sorted sets of binary coalescent times. Each sample value will have cardinality value.size(-1) = leaf_times.size(-1) - 1, so that phylogenies are complete binary trees. This distribution can thus be batched over multiple samples of phylogenies given fixed (number of) leaf times, e.g. over phylogeny samples from BEAST or MrBayes.

This distribution implements log_prob() but not .sample().

See also CoalescentRateLikelihood.

References

[1] J.F.C. Kingman (1982)

“On the Genealogy of Large Populations” Journal of Applied Probability

[2] J.F.C. Kingman (1982)

“The Coalescent” Stochastic Processes and their Applications

[3] A. Popinga, T. Vaughan, T. Statler, A.J. Drummond (2014)

“Inferring epidemiological dynamics with Bayesian coalescent inference: The merits of deterministic and stochastic models” https://arxiv.org/pdf/1407.1792.pdf

Parameters

• leaf_times (torch.Tensor) – Tensor of times of sampling events, i.e. leaf nodes in the phylogeny. These can be arbitrary real numbers with arbitrary order and duplicates.

• rate_grid (torch.Tensor) – Tensor of base coalescent rates (pairwise rate of coalescence). For example in a simple SIR model this might be beta S / I. The rightmost dimension is time, and this tensor represents a (batch of) rates that are piecewise constant in time.

arg_constraints = {'leaf_times': Real(), 'rate_grid': GreaterThan(lower_bound=0.0)}

property duration

expand(batch_shape, _instance=None)[source]

log_prob(value)[source]

Computes likelihood as in equations 7-8 of [3].

This has time complexity O(T + S N log(N)) where T is the number of time steps, N is the number of leaves, and S = sample_shape.numel() is the number of samples of value.

Parameters

value (torch.Tensor) – A tensor of coalescent times. These denote sets of size leaf_times.size(-1) - 1 along the trailing dimension and should be sorted along that dimension.

Returns

Likelihood p(coal_times | leaf_times, rate_grid)

Return type

torch.Tensor

property support

Bases: abc.ABC

abstract condition(context)[source]

Return type

torch.distributions.Distribution

Bases: pyro.distributions.conditional.ConditionalDistribution

clear_cache()[source]

condition(context)[source]

Bases: pyro.distributions.distribution.Distribution, Callable

Degenerate discrete distribution (a single point).

Discrete distribution that assigns probability one to the single element in its support. Delta distribution parameterized by a random choice should not be used with MCMC based inference, as doing so produces incorrect results.

Parameters

• v (torch.Tensor) – The single support element.

• log_density (torch.Tensor) – An optional density for this Delta. This is useful to keep the class of Delta distributions closed under differentiable transformation.

• event_dim (int) – Optional event dimension, defaults to zero.

arg_constraints = {'log_density': Real(), 'v': Dependent()}

expand(batch_shape, _instance=None)[source]

has_rsample = True

log_prob(x)[source]

property mean

rsample(sample_shape=torch.Size([]))[source]

property support

property variance

Bases: pyro.distributions.distribution.Distribution, Callable

Compound distribution comprising of a dirichlet-multinomial pair. The probability of classes (probs for the Multinomial distribution) is unknown and randomly drawn from a Dirichlet distribution prior to a certain number of Categorical trials given by total_count.

Parameters

• concentration (float or torch.Tensor) – concentration parameter (alpha) for the Dirichlet distribution.

• total_count (int or torch.Tensor) – number of Categorical trials.

• is_sparse (bool) – Whether to assume value is mostly zero when computing log_prob(), which can speed up computation when data is sparse.

arg_constraints = {'concentration': IndependentConstraint(GreaterThan(lower_bound=0.0), 1), 'total_count': IntegerGreaterThan(lower_bound=0)}

property concentration

expand(batch_shape, _instance=None)[source]

static infer_shapes(concentration, total_count=())[source]

log_prob(value)[source]

property mean

sample(sample_shape=())[source]

property support

property variance

Bases: pyro.distributions.distribution.Distribution, Callable

Hidden Markov Model with discrete latent state and arbitrary observation distribution.

This uses [1] to parallelize over time, achieving O(log(time)) parallel complexity for computing log_prob(), filter(), and sample().

The event_shape of this distribution includes time on the left:

event_shape = (num_steps,) + observation_dist.event_shape

This distribution supports any combination of homogeneous/heterogeneous time dependency of transition_logits and observation_dist. However, because time is included in this distribution’s event_shape, the homogeneous+homogeneous case will have a broadcastable event_shape with num_steps = 1, allowing log_prob() to work with arbitrary length data:

# homogeneous + homogeneous case:
event_shape = (1,) + observation_dist.event_shape

References:

[1] Simo Sarkka, Angel F. Garcia-Fernandez (2019)

“Temporal Parallelization of Bayesian Filters and Smoothers” https://arxiv.org/pdf/1905.13002.pdf

Parameters

• initial_logits (Tensor) – A logits tensor for an initial categorical distribution over latent states. Should have rightmost size state_dim and be broadcastable to batch_shape + (state_dim,).

• transition_logits (Tensor) – A logits tensor for transition conditional distributions between latent states. Should have rightmost shape (state_dim, state_dim) (old, new), and be broadcastable to batch_shape + (num_steps, state_dim, state_dim).

• observation_dist (Distribution) – A conditional distribution of observed data conditioned on latent state. The .batch_shape should have rightmost size state_dim and be broadcastable to batch_shape + (num_steps, state_dim). The .event_shape may be arbitrary.

• duration (int) – Optional size of the time axis event_shape[0]. This is required when sampling from homogeneous HMMs whose parameters are not expanded along the time axis.

arg_constraints = {'initial_logits': Real(), 'transition_logits': Real()}

expand(batch_shape, _instance=None)[source]

filter(value)[source]

Compute posterior over final state given a sequence of observations.

Parameters

value (Tensor) – A sequence of observations.

Returns

A posterior distribution over latent states at the final time step. result.logits can then be used as initial_logits in a sequential Pyro model for prediction.

Return type

Categorical

log_prob(value)[source]

sample(sample_shape=torch.Size([]))[source]

property support

Bases: pyro.distributions.distribution.Distribution, Callable

Empirical distribution associated with the sampled data. Note that the shape requirement for log_weights is that its shape must match the leftmost shape of samples. Samples are aggregated along the aggregation_dim, which is the rightmost dim of log_weights.

Example:

>>> emp_dist = Empirical(torch.randn(2, 3, 10), torch.ones(2, 3))
>>> emp_dist.batch_shape
torch.Size([2])
>>> emp_dist.event_shape
torch.Size([10])

>>> single_sample = emp_dist.sample()
>>> single_sample.shape
torch.Size([2, 10])
>>> batch_sample = emp_dist.sample((100,))
>>> batch_sample.shape
torch.Size([100, 2, 10])

>>> emp_dist.log_prob(single_sample).shape
torch.Size([2])
>>> # Vectorized samples cannot be scored by log_prob.
>>> with pyro.validation_enabled():
...     emp_dist.log_prob(batch_sample).shape
Traceback (most recent call last):
...
ValueError: ``value.shape`` must be torch.Size([2, 10])

Parameters

• samples (torch.Tensor) – samples from the empirical distribution.

• log_weights (torch.Tensor) – log weights (optional) corresponding to the samples.

arg_constraints = {}

enumerate_support(expand=True)[source]

See pyro.distributions.torch_distribution.TorchDistribution.enumerate_support()

property event_shape

See pyro.distributions.torch_distribution.TorchDistribution.event_shape()

has_enumerate_support = True

log_prob(value)[source]

Returns the log of the probability mass function evaluated at value. Note that this currently only supports scoring values with empty sample_shape.

Parameters

value (torch.Tensor) – scalar or tensor value to be scored.

property log_weights

property mean

See pyro.distributions.torch_distribution.TorchDistribution.mean()

sample(sample_shape=torch.Size([]))[source]

See pyro.distributions.torch_distribution.TorchDistribution.sample()

property sample_size

Number of samples that constitute the empirical distribution.

Return int

number of samples collected.

support = Real()

property variance

See pyro.distributions.torch_distribution.TorchDistribution.variance()

Bases: pyro.distributions.distribution.Distribution, Callable

EXPERIMENTAL BetaBinomial distribution extended to have logical support the entire integers and to allow arbitrary integer total_count. Numerical support is still the integer interval [0, total_count].

arg_constraints = {'concentration0': GreaterThan(lower_bound=0.0), 'concentration1': GreaterThan(lower_bound=0.0), 'total_count': Integer}

log_prob(value)[source]

support = Integer

Bases: pyro.distributions.distribution.Distribution, Callable

EXPERIMENTAL Binomial distribution extended to have logical support the entire integers and to allow arbitrary integer total_count. Numerical support is still the integer interval [0, total_count].

arg_constraints = {'logits': Real(), 'probs': Interval(lower_bound=0.0, upper_bound=1.0), 'total_count': Integer}

log_prob(value)[source]

support = Integer

Bases: pyro.distributions.distribution.Distribution, Callable

Equivalent to TransformedDistribution(base_dist, AbsTransform()), but additionally supports log_prob() .

Parameters

base_dist (Distribution) – The distribution to reflect.

expand(batch_shape, _instance=None)[source]