Distributions

class irt.distributions.Beta(*args: Any, **kwargs: Any)[source]

Beta distribution parameterized by concentration1 and concentration0.

Example:

>>> m = Beta(torch.tensor([0.5]), torch.tensor([0.5]))
>>> m.sample()
tensor([0.1046])

Args:

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)

entropy() → torch.Tensor[source]

Computes the entropy of the Beta distribution.

Returns:: Entropy of the distribution.

expand(batch_shape: torch.Size, _instance: Optional[Beta] = None) → Beta[source]

Expands the Beta distribution to a new batch shape.

Args:: batch_shape: Desired batch shape. _instance: Instance to validate.
Returns:: A new Beta distribution instance with expanded parameters.

log_prob(value: torch.Tensor) → torch.Tensor[source]

Computes the log probability density of a value under the Beta distribution.

Args:: value: Value to evaluate.
Returns:: Log probability of the value.

property mean: torch.Tensor

Computes the mean of the Beta distribution.

Returns:: torch.Tensor: Mean of the distribution.

property mode: torch.Tensor

Computes the mode of the Beta distribution.

Returns:: torch.Tensor: Mode of the distribution.

rsample(sample_shape: torch.types._size = ()) → torch.Tensor[source]

Generates a reparameterized sample from the Beta distribution.

Args:: sample_shape (_size): Shape of the sample.
Returns:: torch.Tensor: Sample from the Beta distribution.

property variance: torch.Tensor

Computes the variance of the Beta distribution.

Returns:: torch.Tensor: Variance of the distribution.

class irt.distributions.Dirichlet(*args: Any, **kwargs: Any)[source]

Dirichlet distribution parameterized by a concentration vector.

The Dirichlet distribution is a multivariate generalization of the Beta distribution. It is commonly used in Bayesian statistics, particularly for modeling proportions.

entropy() → torch.Tensor[source]

Computes the entropy of the Dirichlet distribution.

Returns:: torch.Tensor: Entropy of the distribution.

expand(batch_shape: torch.Size, _instance: Optional[Dirichlet] = None) → Dirichlet[source]

Expands the distribution parameters to a new batch shape.

Args:: batch_shape (torch.Size): Desired batch shape. _instance (Optional): Instance to validate.
Returns:: A new Dirichlet distribution instance with expanded parameters.

log_prob(value: torch.Tensor) → torch.Tensor[source]

Computes the log probability density for a given value.

Args:: value (torch.Tensor): Value to evaluate the log probability at.
Returns:: torch.Tensor: Log probability density of the value.

property mean: torch.Tensor

Computes the mean of the Dirichlet distribution.

Returns:: Mean vector, calculated as concentration / concentration.sum(-1, keepdim=True).

property mode: torch.Tensor

Computes the mode of the Dirichlet distribution.

Note:

The mode is defined only when all concentration values are > 1.
For concentrations ≤ 1, the mode vector is clamped to enforce positivity.

Returns:

Mode vector.

rsample(sample_shape: torch.types._size = ()) → torch.Tensor[source]

Generates a reparameterized sample from the Dirichlet distribution.

Args:: sample_shape (_size): Desired sample shape.
Returns:: torch.Tensor: A reparameterized sample.

property variance: torch.Tensor

Computes the variance of the Dirichlet distribution.

Returns:: Variance vector for each component.

class irt.distributions.Gamma(*args: Any, **kwargs: Any)[source]

Gamma distribution parameterized by concentration (shape) and rate (inverse scale). The Gamma distribution is often used to model the time until an event occurs, and it is a continuous probability distribution defined for non-negative real values.

cdf(value: torch.Tensor) → torch.Tensor[source]

Computes the cumulative distribution function (CDF) for the Gamma distribution.

Args:: value (torch.Tensor): Value to evaluate the CDF at.
Returns:: torch.Tensor: CDF of the given value.

entropy() → torch.Tensor[source]

Computes the entropy of the Gamma distribution.

Returns:: torch.Tensor: Entropy of the distribution.

expand(batch_shape: torch.Size, _instance: Optional[Gamma] = None) → Gamma[source]

Expands the distribution parameters to a new batch shape.

Args:: batch_shape (torch.Size): Desired batch shape. _instance (Optional): Instance to validate.
Returns:: Gamma: A new Gamma distribution instance with expanded parameters.

log_prob(value: torch.Tensor) → torch.Tensor[source]

Computes the log probability density for a given value.

Args:: value (torch.Tensor): Value to evaluate the log probability at.
Returns:: torch.Tensor: Log probability density of the given value.

property mean: torch.Tensor

Computes the mean of the Gamma distribution.

Returns:: torch.Tensor: Mean of the distribution, calculated as concentration / rate.

property mode: torch.Tensor

Computes the mode of the Gamma distribution.

Note:

The mode is defined only for concentration > 1. For concentration <= 1, the mode is clamped to 0.

Returns:

torch.Tensor: Mode of the distribution.

rsample(sample_shape: torch.types._size = torch.Size) → torch.Tensor[source]

Generates a reparameterized sample from the Gamma distribution.

Args:: sample_shape (_size): Shape of the sample.
Returns:: torch.Tensor: A reparameterized sample.

property variance: torch.Tensor

Computes the variance of the Gamma distribution.

Returns:: torch.Tensor: Variance of the distribution, calculated as concentration / rate^2.

class irt.distributions.MixtureSameFamily(*args: Any, **kwargs: Any)[source]

Represents a mixture of distributions from the same family. Supporting reparameterized sampling for gradient-based optimization.

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

Generates a reparameterized sample from the mixture of distributions.

This method generates a sample, applies a distributional transformation, and computes a surrogate sample to enable gradient flow during optimization.

Args:: sample_shape (torch.Size): The shape of the sample to generate.
Returns:: torch.Tensor: A reparameterized sample with gradients enabled.

class irt.distributions.Normal(*args: Any, **kwargs: Any)[source]

Represents the Normal (Gaussian) distribution with specified mean (loc) and standard deviation (scale). Inherits from PyTorch’s ExponentialFamily distribution class.

cdf(value: torch.Tensor) → torch.Tensor[source]

Computes the cumulative distribution function (CDF) of the distribution at a given value.

Args:: value (torch.Tensor): The value at which to evaluate the CDF.
Returns:: torch.Tensor: The probability that a random variable from the distribution is less than or equal to value.

entropy() → torch.Tensor[source]

Computes the entropy of the distribution.

Returns:: torch.Tensor: The entropy of the Normal distribution, which is a measure of uncertainty.

expand(batch_shape: torch.Size, _instance: Optional[Normal] = None) → Normal[source]

Expands the distribution parameters to a new batch shape.

Args:: batch_shape (torch.Size): Desired batch size for the expanded distribution. _instance (Optional): Instance to check for validity.
Returns:: Normal: A new Normal distribution with parameters expanded to the specified batch shape.

icdf(value: torch.Tensor) → torch.Tensor[source]

Computes the inverse cumulative distribution function (quantile function) at a given value.

Args:: value (torch.Tensor): The probability value at which to evaluate the inverse CDF.
Returns:: torch.Tensor: The quantile corresponding to value.

log_prob(value: torch.Tensor) → torch.Tensor[source]

Computes the log probability density of the distribution at a given value.

Args:: value (torch.Tensor): The value at which to evaluate the log probability.
Returns:: torch.Tensor: The log probability density at value.

property mean: torch.Tensor

Returns the mean of the distribution.

Returns:: torch.Tensor: The mean (location) parameter loc.

property mode: torch.Tensor

Returns the mode of the distribution.

Returns:: torch.Tensor: The mode (equal to loc in a Normal distribution).

rsample(sample_shape: torch.types._size = torch.Size) → torch.Tensor[source]

Generates a reparameterized sample from the Normal distribution, enabling gradient backpropagation.

Returns:: torch.Tensor: A tensor containing a reparameterized sample, useful for gradient-based optimization.

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

Generates a sample from the Normal distribution using torch.normal.

Args:: sample_shape (torch.Size): Shape of the sample to generate.
Returns:: torch.Tensor: A tensor with samples from the Normal distribution, detached from the computation graph.

property stddev: torch.Tensor

Returns the standard deviation of the distribution.

Returns:: torch.Tensor: The standard deviation (scale) parameter scale.

property variance: torch.Tensor

Returns the variance of the distribution.

Returns:: torch.Tensor: The variance, computed as scale ** 2.

class irt.distributions.StudentT(*args: Any, **kwargs: Any)[source]

Student’s t-distribution parameterized by degrees of freedom (df), location (loc), and scale (scale).

This distribution is commonly used for robust statistical modeling, particularly when the data may have outliers or heavier tails than a Normal distribution.

entropy() → torch.Tensor[source]

Computes the entropy of the Student’s t-distribution.

Returns:: torch.Tensor: Entropy of the distribution.

expand(batch_shape: torch.Size, _instance: Optional[StudentT] = None) → StudentT[source]

Expands the distribution parameters to a new batch shape.

Args:: batch_shape (torch.Size): Desired batch size for the expanded distribution. _instance (Optional): Instance to validate.
Returns:: StudentT: A new StudentT distribution with expanded parameters.

log_prob(value: torch.Tensor) → torch.Tensor[source]

Computes the log probability density for a given value.

Args:: value (torch.Tensor): Value to evaluate the log probability at.
Returns:: torch.Tensor: Log probability density of the given value.

property mean: torch.Tensor

Computes the mean of the distribution.

Note: The mean is undefined when df <= 1.

Returns:: torch.Tensor: Mean of the distribution, or NaN for undefined cases.

property mode: torch.Tensor

Computes the mode of the distribution.

Returns:: torch.Tensor: Mode of the distribution, which is equal to loc.

rsample(sample_shape: torch.types._size = torch.Size) → torch.Tensor[source]

Generates a reparameterized sample from the Student’s t-distribution.

Args:: sample_shape (_size): Shape of the sample.
Returns:: torch.Tensor: Reparameterized sample, enabling gradient tracking.

property variance: torch.Tensor

Computes the variance of the distribution.

Note:

Variance is infinite for 1 < df <= 2.
Variance is undefined (NaN) for df <= 1.

Returns:

torch.Tensor: Variance of the distribution, or appropriate values for edge cases.

class irt.distributions.VonMises(*args: Any, **kwargs: Any)[source]

Von Mises distribution class for circular data.

log_prob(value: torch.Tensor) → torch.Tensor[source]

Compute the log probability of the given value.

Args:: value: Tensor of values.
Returns:: Tensor of log probabilities.

property mean: torch.Tensor: Mean of the distribution.

rsample(sample_shape: torch.types._size = torch.Size) → torch.Tensor[source]: Generate reparameterized samples from the distribution

sample(sample_shape: torch.types._size = torch.Size) → torch.Tensor

The sampling algorithm for the von Mises distribution is based on the following paper: D.J. Best and N.I. Fisher, “Efficient simulation of the von Mises distribution.” Applied Statistics (1979): 152-157.

Sampling is always done in double precision internally to avoid a hang in _rejection_sample() for small values of the concentration, which starts to happen for single precision around 1e-4 (see issue #88443).

property variance: torch.Tensor: Variance of the distribution.

irt.distributions.cdf_func(concentration: torch.Tensor, x: torch.Tensor) → torch.Tensor[source]

Approximate the CDF of the von Mises distribution.

Args:: concentration (torch.Tensor): Concentration parameter (kappa). x (torch.Tensor): Input tensor.
Returns:: torch.Tensor: Approximate CDF values.

irt.distributions.cosxm1(x: torch.Tensor) → torch.Tensor[source]

Compute cos(x) - 1 using a numerically stable formula.

Args:: x (torch.Tensor): Input tensor.
Returns:: torch.Tensor: Output tensor, cos(x) - 1.

irt.distributions.von_mises_cdf_normal(x: torch.Tensor, concentration: torch.Tensor) → Tuple[torch.Tensor, torch.Tensor][source]

Compute the CDF of the von Mises distribution using a normal approximation.

Args:: x (torch.Tensor): Input tensor. concentration (torch.Tensor): Concentration parameter (kappa).
Returns:: Tuple[torch.Tensor, torch.Tensor]: CDF and its gradient with respect to concentration.

irt.distributions.von_mises_cdf_series(x: torch.Tensor, concentration: torch.Tensor, num_terms: int) → Tuple[torch.Tensor, torch.Tensor][source]

Compute the CDF of the von Mises distribution using a series approximation.

Args:: x (torch.Tensor): Input tensor. concentration (torch.Tensor): Concentration parameter (kappa). num_terms (int): Number of terms in the series.
Returns:: Tuple[torch.Tensor, torch.Tensor]: CDF and its gradient with respect to concentration.