probability

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package probability provides tools for working with discrete probability spaces, random variables, and finite-state Markov chains using only the Go standard library.

The central type is Distribution, a finitely-supported discrete probability distribution over real-valued outcomes. It offers the full complement of summary statistics (expectation, variance, higher moments, skewness, excess kurtosis, entropy), the standard generating functions (moment-generating, cumulant-generating, probability-generating and the characteristic function), cumulative and quantile queries, random-variable transforms (affine maps and arbitrary functions), and convolution of independent sums.

JointDistribution models a bivariate discrete distribution and exposes its marginals, conditionals, covariance and correlation. A small set of package-level functions (Bayes, BayesPosterior, TotalProbability, ConditionalProbability, UnionProbability and friends) cover the elementary laws of probability and Bayesian updating.

MarkovChain wraps a row-stochastic transition matrix and computes n-step transition matrices, the evolution of a distribution, stationary distributions of irreducible chains, and the absorbing-chain quantities (fundamental matrix, expected steps to absorption, absorption probabilities).

All routines are deterministic and depend only on the standard library. Distributions produced by the constructors and transforms keep their support sorted in ascending order with duplicate outcomes merged, so probability-mass and cumulative queries are unambiguous.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AreIndependent 

func AreIndependent(pA, pB, pAandB float64) bool

AreIndependent reports whether events A and B are independent, i.e. whether P(A ∩ B) equals P(A)·P(B) within [probabilityTol].

func Bayes 

func Bayes(pBgivenA, pA, pB float64) (float64, error)

Bayes returns the posterior probability P(A | B) via Bayes' theorem, P(B | A)·P(A) / P(B). It returns an error if any argument is outside [0, 1] or if P(B) is zero.

func BayesPosterior 

func BayesPosterior(priors, likelihoods []float64) ([]float64, error)

BayesPosterior returns the full posterior distribution over a partition of hypotheses {A_i}: posterior[i] = priors[i]·likelihoods[i] / Σ_k priors[k]·likelihoods[k], where likelihoods[i] = P(evidence | A_i). It returns an error if the slices differ in length, are empty, the priors do not sum to one, or the total evidence probability is zero.

func Complement 

func Complement(p float64) float64

Complement returns the probability of the complementary event, 1 - p. It returns NaN if p is outside [0, 1].

func ConditionalProbability 

func ConditionalProbability(pAandB, pB float64) (float64, error)

ConditionalProbability returns P(A | B) = P(A ∩ B) / P(B). It returns an error if either probability is outside [0, 1], if the joint probability exceeds P(B), or if P(B) is zero.

func JointProbabilityIndependent 

func JointProbabilityIndependent(pA, pB float64) float64

JointProbabilityIndependent returns P(A ∩ B) = P(A)·P(B) under the assumption that A and B are independent.

func OddsFromProbability 

func OddsFromProbability(p float64) float64

OddsFromProbability converts a probability p in [0, 1) to odds p / (1 - p). It returns +Inf as p approaches one and NaN if p is outside [0, 1].

func ProbabilityFromOdds 

func ProbabilityFromOdds(o float64) float64

ProbabilityFromOdds converts non-negative odds o to the probability o / (1 + o). It returns NaN for negative odds.

func TotalProbability 

func TotalProbability(priors, likelihoods []float64) (float64, error)

TotalProbability returns P(B) = Σ_i priors[i]·likelihoods[i] via the law of total probability, where priors is a partition {A_i} with P(A_i) = priors[i] and likelihoods[i] = P(B | A_i). It returns an error if the slices differ in length, are empty, or the priors do not sum to one within [probabilityTol].

func UnionProbability 

func UnionProbability(pA, pB, pAandB float64) float64

UnionProbability returns P(A ∪ B) = P(A) + P(B) - P(A ∩ B) via the inclusion-exclusion principle.

Types

type Distribution 

type Distribution struct {
	// Outcomes holds the distinct outcome values in ascending order.
	Outcomes []float64
	// Probs holds the probability mass of the corresponding outcome.
	Probs []float64
}

Distribution is a finitely-supported discrete probability distribution over real-valued outcomes. Outcomes[i] occurs with probability Probs[i]. The two slices always have equal length.

Distributions produced by the constructors and by the transform and convolution methods maintain a canonical form: Outcomes is sorted in strictly ascending order (duplicate outcomes are merged by summing their probabilities) and every probability is non-negative and sums to one within [probabilityTol]. Methods assume this invariant; mutating the fields directly may invalidate cumulative and quantile queries.

func Bernoulli 

func Bernoulli(p float64) (Distribution, error)

Bernoulli returns the Bernoulli distribution with success probability p, supported on {0, 1} with P(1) = p and P(0) = 1-p. It returns an error if p is outside [0, 1].

func Binomial 

func Binomial(n int, p float64) (Distribution, error)

Binomial returns the binomial distribution for n independent Bernoulli trials each with success probability p, supported on {0, 1, …, n}. It returns an error if n is negative or p is outside [0, 1].

func DiscreteUniform 

func DiscreteUniform(a, b int) (Distribution, error)

DiscreteUniform returns the uniform distribution over the consecutive integers a, a+1, …, b (inclusive), each with probability 1/(b-a+1). It returns an error if b < a.

func Geometric 

func Geometric(p float64, kmax int) (Distribution, error)

Geometric returns the geometric distribution for the number of trials up to and including the first success (support {1, 2, …, kmax}) with per-trial success probability p, truncated to kmax and renormalized. It returns an error if p is outside (0, 1] or kmax is less than one.

func Mixture 

func Mixture(weights []float64, components []Distribution) (Distribution, error)

Mixture returns the finite mixture Σ_k weights[k]·components[k], a single Distribution whose outcomes are the union of the components' supports with probabilities blended according to weights. The weights must be non-negative and sum to one within [probabilityTol]. It returns an error if the slice lengths differ, either slice is empty, or the weights are invalid.

func NewDistribution 

func NewDistribution(outcomes, probs []float64) (Distribution, error)

NewDistribution builds a Distribution from parallel outcome and probability slices. Duplicate outcomes are merged and the support is sorted. It returns an error if the slices differ in length, are empty, contain a negative or non-finite probability, or if the probabilities do not sum to one within [probabilityTol].

func Poisson 

func Poisson(lambda float64, kmax int) (Distribution, error)

Poisson returns the Poisson distribution with rate lambda truncated to the support {0, 1, …, kmax} and renormalized so its probabilities sum to one. For a kmax comfortably larger than lambda the truncation error is negligible. It returns an error if lambda is negative or kmax is negative.

func Uniform 

func Uniform(outcomes []float64) (Distribution, error)

Uniform returns the uniform distribution over the given distinct outcomes, assigning probability 1/n to each. It returns an error if outcomes is empty.

func (Distribution) Affine 

func (d Distribution) Affine(a, b float64) Distribution

Affine returns the distribution of aX + b, applying a scale followed by a shift in a single pass.

func (Distribution) CDF 

func (d Distribution) CDF(x float64) float64

CDF returns the cumulative distribution function P(X <= x): the total probability of all outcomes less than or equal to x.

func (Distribution) CGF 

func (d Distribution) CGF(t float64) float64

CGF returns the cumulant-generating function K(t) = ln E[e^{tX}] = ln M(t) evaluated at t. Its derivatives at zero give the cumulants of X.

func (Distribution) CentralMoment 

func (d Distribution) CentralMoment(k int) float64

CentralMoment returns the k-th central moment E[(X - E[X])^k]. CentralMoment(2) is the variance. It returns NaN for negative k.

func (Distribution) CharacteristicFunction 

func (d Distribution) CharacteristicFunction(t float64) complex128

CharacteristicFunction returns φ(t) = E[e^{itX}], the characteristic function of X evaluated at real argument t, as a complex value.

func (Distribution) Convolve 

func (d Distribution) Convolve(other Distribution) Distribution

Convolve returns the distribution of the sum X + Y of two independent random variables X (the receiver) and Y (the argument): every pair of outcomes is added and the joint probabilities Probs[i]·other.Probs[j] accumulated on the resulting sums.

func (Distribution) ConvolvePower 

func (d Distribution) ConvolvePower(n int) (Distribution, error)

ConvolvePower returns the distribution of the sum of n independent copies of X (the receiver): X_1 + X_2 + … + X_n. ConvolvePower(0) is a point mass at zero (the empty sum) and ConvolvePower(1) is the receiver itself. It uses exponentiation by squaring, so it performs O(log n) convolutions. It returns an error for negative n.

func (Distribution) Entropy 

func (d Distribution) Entropy() float64

Entropy returns the Shannon entropy H(X) = -Σ_i Probs[i] ln Probs[i] measured in nats. Outcomes with zero probability contribute nothing.

func (Distribution) EntropyBits 

func (d Distribution) EntropyBits() float64

EntropyBits returns the Shannon entropy measured in bits, i.e. the entropy in nats divided by ln 2.

func (Distribution) Expectation 

func (d Distribution) Expectation(g func(float64) float64) float64

Expectation returns E[g(X)] = Σ_i g(Outcomes[i]) · Probs[i], the expected value of the arbitrary function g applied to the random variable.

func (Distribution) Kurtosis 

func (d Distribution) Kurtosis() float64

Kurtosis returns the excess kurtosis, E[(X - E[X])^4] / σ^4 - 3, which is zero for a normal distribution. It returns NaN when the standard deviation is zero.

func (Distribution) Len 

func (d Distribution) Len() int

Len returns the number of distinct outcomes in the support.

func (Distribution) MGF 

func (d Distribution) MGF(t float64) float64

MGF returns the moment-generating function M(t) = E[e^{tX}] evaluated numerically at t. Derivatives of M at t = 0 give the raw moments of X.

func (Distribution) MGFDerivativeMoment 

func (d Distribution) MGFDerivativeMoment(k int, h float64) float64

MGFDerivativeMoment returns the k-th raw moment estimated by numerically differentiating the moment-generating function k times at t = 0 using a central finite-difference stencil with step h. It is provided as a numerical cross-check of Distribution.Moment; for exact moments prefer that method. It returns NaN for negative k or non-positive h.

func (Distribution) Max 

func (d Distribution) Max() float64

Max returns the largest outcome in the support.

func (Distribution) Mean 

func (d Distribution) Mean() float64

Mean returns the expected value E[X] of the distribution.

func (Distribution) Median 

func (d Distribution) Median() float64

Median returns the 0.5 quantile of the distribution.

func (Distribution) Min 

func (d Distribution) Min() float64

Min returns the smallest outcome in the support.

func (Distribution) Mode 

func (d Distribution) Mode() float64

Mode returns the outcome carrying the greatest probability mass. When several outcomes tie, the smallest such outcome is returned.

func (Distribution) Moment 

func (d Distribution) Moment(k int) float64

Moment returns the k-th raw moment E[X^k]. Moment(0) is one and Moment(1) is the mean. It returns NaN for negative k.

func (Distribution) Normalize 

func (d Distribution) Normalize() (Distribution, error)

Normalize returns a copy of the distribution whose probabilities are rescaled to sum to exactly one. It is useful after manually assembling unnormalized weights. It returns an error if the total weight is not strictly positive.

func (Distribution) PGF 

func (d Distribution) PGF(z float64) float64

PGF returns the probability-generating function G(z) = E[z^X] = Σ_i Probs[i] z^{Outcomes[i]} evaluated at z. It is most meaningful for distributions on the non-negative integers, where the k-th derivative at zero recovers k!·P(X=k).

func (Distribution) PMF 

func (d Distribution) PMF(x float64) float64

PMF returns the probability mass P(X = x), i.e. the probability assigned to the outcome exactly equal to x, or zero if x is not in the support.

func (Distribution) Quantile 

func (d Distribution) Quantile(q float64) float64

Quantile returns the smallest outcome x such that P(X <= x) >= q, i.e. the generalized inverse of the CDF. q is clamped to [0, 1]; a q of zero returns the minimum outcome and a q of one returns the maximum.

func (Distribution) Scale 

func (d Distribution) Scale(a float64) Distribution

Scale returns the distribution of aX, multiplying every outcome by a. The probabilities are unchanged. When a is zero the result is a point mass at zero.

func (Distribution) Shift 

func (d Distribution) Shift(b float64) Distribution

Shift returns the distribution of X + b, translating every outcome by b. The probabilities are unchanged.

func (Distribution) Skewness 

func (d Distribution) Skewness() float64

Skewness returns the standardized third central moment, E[(X - E[X])^3] / σ^3, a dimensionless measure of asymmetry. It returns NaN when the standard deviation is zero.

func (Distribution) Standardize 

func (d Distribution) Standardize() (Distribution, error)

Standardize returns the distribution of (X - E[X]) / σ, the standardized random variable with mean zero and unit variance. It returns an error when the standard deviation is zero.

func (Distribution) StdDev 

func (d Distribution) StdDev() float64

StdDev returns the standard deviation, the non-negative square root of the variance.

func (Distribution) Support 

func (d Distribution) Support() []float64

Support returns a copy of the outcome values in ascending order.

func (Distribution) Transform 

func (d Distribution) Transform(g func(float64) float64) Distribution

Transform returns the distribution of the random variable Y = g(X), applying g to every outcome. Outcomes that g maps to the same value have their probabilities merged, so the result keeps the canonical sorted-unique form.

func (Distribution) Validate 

func (d Distribution) Validate() error

Validate reports whether the distribution is well-formed: equal-length non-empty slices, non-negative finite probabilities, and a total mass of one within [probabilityTol]. It returns nil when the distribution is valid.

func (Distribution) Variance 

func (d Distribution) Variance() float64

Variance returns Var(X) = E[(X - E[X])^2], the population variance of the distribution.

type JointDistribution 

type JointDistribution struct {
	// X holds the distinct outcome values of the first variable.
	X []float64
	// Y holds the distinct outcome values of the second variable.
	Y []float64
	// P is the joint probability grid indexed as P[i][j] = P(X[i], Y[j]).
	P [][]float64
}

JointDistribution is a bivariate discrete distribution over a grid of outcomes. X holds the distinct outcome values of the first variable (rows) and Y holds those of the second (columns); P[i][j] is the joint probability P(X = X[i], Y = Y[j]). The probabilities are non-negative and sum to one.

func IndependentJoint 

func IndependentJoint(a, b Distribution) JointDistribution

IndependentJoint builds the joint distribution of two independent random variables from their marginals, setting P[i][j] = a.Probs[i]·b.Probs[j]. The resulting joint is independent by construction.

func NewJointDistribution 

func NewJointDistribution(x, y []float64, p [][]float64) (JointDistribution, error)

NewJointDistribution builds a JointDistribution and validates it: X and Y must be non-empty, P must be a len(X)-by-len(Y) grid of non-negative finite probabilities summing to one within [probabilityTol]. The inputs are copied.

func (JointDistribution) ConditionalXGivenY 

func (j JointDistribution) ConditionalXGivenY(k int) (Distribution, error)

ConditionalXGivenY returns the conditional distribution of X given Y = Y[k], i.e. P(X = X[i] | Y = Y[k]) = P[i][k] / P(Y = Y[k]). It returns an error if k is out of range or the conditioning event has zero probability.

func (JointDistribution) ConditionalYGivenX 

func (j JointDistribution) ConditionalYGivenX(i int) (Distribution, error)

ConditionalYGivenX returns the conditional distribution of Y given X = X[i], i.e. P(Y = Y[k] | X = X[i]) = P[i][k] / P(X = X[i]). It returns an error if i is out of range or the conditioning event has zero probability.

func (JointDistribution) Correlation 

func (j JointDistribution) Correlation() float64

Correlation returns the Pearson correlation coefficient Cov(X, Y) / (σ_X · σ_Y), a value in [-1, 1]. It returns NaN when either marginal has zero standard deviation.

func (JointDistribution) Covariance 

func (j JointDistribution) Covariance() float64

Covariance returns Cov(X, Y) = E[XY] - E[X]·E[Y], the covariance of the two variables under the joint distribution.

func (JointDistribution) ExpectationXY 

func (j JointDistribution) ExpectationXY(g func(x, y float64) float64) float64

ExpectationXY returns E[g(X, Y)] = Σ_{i,k} g(X[i], Y[k]) · P[i][k] for an arbitrary function g of the two variables.

func (JointDistribution) Independent 

func (j JointDistribution) Independent() bool

Independent reports whether X and Y are independent, i.e. whether P[i][k] equals P(X = X[i])·P(Y = Y[k]) for every cell within [probabilityTol].

func (JointDistribution) MarginalX 

func (j JointDistribution) MarginalX() Distribution

MarginalX returns the marginal distribution of X obtained by summing the joint probabilities across the Y axis for each row.

func (JointDistribution) MarginalY 

func (j JointDistribution) MarginalY() Distribution

MarginalY returns the marginal distribution of Y obtained by summing the joint probabilities across the X axis for each column.

type MarkovChain 

type MarkovChain struct {
	// P is the square row-stochastic transition matrix.
	P [][]float64
}

MarkovChain is a finite-state discrete-time Markov chain represented by a row-stochastic transition matrix P, where P[i][j] is the probability of moving from state i to state j in one step. Each row is non-negative and sums to one.

func NewMarkovChain 

func NewMarkovChain(p [][]float64) (MarkovChain, error)

NewMarkovChain builds a MarkovChain from a transition matrix, validating that it is square, non-negative, and row-stochastic (each row sums to one within [probabilityTol]). The matrix is copied. It returns an error otherwise.

func (MarkovChain) AbsorbingStates 

func (m MarkovChain) AbsorbingStates() []int

AbsorbingStates returns the indices of the absorbing states, those i with P[i][i] equal to one (and hence no probability of leaving), in ascending order.

func (MarkovChain) AbsorptionProbabilities 

func (m MarkovChain) AbsorptionProbabilities() ([][]float64, error)

AbsorptionProbabilities returns the matrix B = N·R of absorption probabilities, where N is the fundamental matrix and R is the transient-to-absorbing submatrix of P. Rows are indexed in the order of MarkovChain.TransientStates and columns in the order of MarkovChain.AbsorbingStates; B[i][k] is the probability that a chain started in transient state i is eventually absorbed in absorbing state k. It returns an error if the chain is not absorbing.

func (MarkovChain) DistributionAfter 

func (m MarkovChain) DistributionAfter(initial []float64, n int) ([]float64, error)

DistributionAfter returns the state distribution after n steps starting from the initial distribution, i.e. initial·P^n. initial must have length equal to the number of states. It returns an error on a length mismatch or negative n.

func (MarkovChain) ExpectedStepsToAbsorption 

func (m MarkovChain) ExpectedStepsToAbsorption() ([]float64, error)

ExpectedStepsToAbsorption returns, for each state, the expected number of steps until the chain is absorbed. The result is a full-length vector indexed by state: absorbing states have value zero and transient states hold the expected number of steps to absorption (the corresponding row sum of the fundamental matrix). It returns an error if the chain is not absorbing.

func (MarkovChain) FundamentalMatrix 

func (m MarkovChain) FundamentalMatrix() ([][]float64, error)

FundamentalMatrix returns the fundamental matrix N = (I - Q)^{-1} of an absorbing chain, where Q is the transient-to-transient submatrix of P. Rows and columns are indexed in the order returned by MarkovChain.TransientStates. Entry N[i][j] is the expected number of visits to transient state j before absorption, starting from transient state i. It returns an error if the chain is not absorbing.

func (MarkovChain) IsAbsorbing 

func (m MarkovChain) IsAbsorbing() bool

IsAbsorbing reports whether the chain is an absorbing Markov chain: it has at least one absorbing state and every state can reach an absorbing state.

func (MarkovChain) IsIrreducible 

func (m MarkovChain) IsIrreducible() bool

IsIrreducible reports whether the chain is irreducible, i.e. every state is reachable from every other state.

func (MarkovChain) IsRegular 

func (m MarkovChain) IsRegular() bool

IsRegular reports whether the chain is regular (primitive): some power P^k has all strictly positive entries. A regular chain is irreducible and aperiodic and has a unique limiting distribution. By Wielandt's bound it suffices to check powers up to (n-1)^2 + 1.

func (MarkovChain) MeanRecurrenceTimes 

func (m MarkovChain) MeanRecurrenceTimes() ([]float64, error)

MeanRecurrenceTimes returns the vector of mean recurrence times of an irreducible chain, where entry i is 1/π_i and π is the stationary distribution. It returns an error if the stationary distribution cannot be computed or has a zero component.

func (MarkovChain) NStep 

func (m MarkovChain) NStep(n int) ([][]float64, error)

NStep returns the n-step transition matrix P^n, whose (i, j) entry is the probability of moving from state i to state j in exactly n steps. NStep(0) is the identity. It returns an error for negative n.

func (MarkovChain) Reachable 

func (m MarkovChain) Reachable(i, j int) bool

Reachable reports whether state j is reachable from state i in zero or more steps (a state is always reachable from itself).

func (MarkovChain) Size 

func (m MarkovChain) Size() int

Size returns the number of states in the chain.

func (MarkovChain) StationaryDistribution 

func (m MarkovChain) StationaryDistribution() ([]float64, error)

StationaryDistribution returns a stationary distribution π satisfying πP = π and Σ π = 1. For an irreducible chain the stationary distribution is unique. It solves the linear system (P^T - I)π = 0 with a normalization constraint via Gaussian elimination. It returns an error if the system is singular (e.g. a reducible chain without a unique stationary distribution).

func (MarkovChain) Step 

func (m MarkovChain) Step(dist []float64) ([]float64, error)

Step advances a distribution over states by one transition, returning the row vector dist·P. dist must have length equal to the number of states. It returns an error on a length mismatch.

func (MarkovChain) TransientStates 

func (m MarkovChain) TransientStates() []int

TransientStates returns the indices of the non-absorbing states in ascending order. For an absorbing chain these are exactly the transient states.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.