distmat

Documentation

Overview

Package distmat provides probability distributions over matrices.

Index

• type UniformPermutation
  • func NewUniformPermutation(src rand.Source) *UniformPermutation
  • func (p *UniformPermutation) PermTo(dst *mat.Dense)
• type UnitVector
  • func NewUnitVector(src rand.Source) *UnitVector
  • func (u *UnitVector) UnitVecTo(dst *mat.VecDense)
• type Wishart
  • func NewWishart(v mat.Symmetric, nu float64, src rand.Source) (*Wishart, bool)
  • func (w *Wishart) LogProbSym(x mat.Symmetric) float64
  • func (w *Wishart) LogProbSymChol(cholX *mat.Cholesky) float64
  • func (w *Wishart) MeanSymTo(dst *mat.SymDense)
  • func (w *Wishart) ProbSym(x mat.Symmetric) float64
  • func (w *Wishart) RandCholTo(dst *mat.Cholesky)
  • func (w *Wishart) RandSymTo(dst *mat.SymDense)

Examples

• UnitVector

Types

type UniformPermutation

type UniformPermutation struct {
	// contains filtered or unexported fields
}

UniformPermutation is a uniform distribution over the n! permutation matrices of size n×n for a given n.

func NewUniformPermutation

func NewUniformPermutation(src rand.Source) *UniformPermutation

NewUniformPermutation constructs a new permutation matrix generator using the given random source.

func (*UniformPermutation) PermTo

func (p *UniformPermutation) PermTo(dst *mat.Dense)

PermTo sets the given matrix to be a random permutation matrix. It does not zero the destination's elements, so it is the responsibility of the caller to ensure it is correctly conditioned prior to the call.

PermTo panics if dst is not square.

type UnitVector

type UnitVector struct {
	// contains filtered or unexported fields
}

UnitVector is a uniform distribution over the surface of a sphere.

Example

ExampleUnitVector uses the UnitVector distribution to take a random walk in n-space. At the end it computes how far from the origin the walk finished.

package main

import (
	"fmt"

	"golang.org/x/exp/rand"

	"gonum.org/v1/gonum/mat"
	"gonum.org/v1/gonum/stat/distmat"
)

func main() {
	src := rand.NewSource(1)
	rnd := rand.New(src)
	dist := distmat.NewUnitVector(src)

	// Draw a random dimension for the space to walk through.
	nDim := 1 + rnd.Intn(100)
	// Vectors to hold the current position and next step.
	position := mat.NewVecDense(nDim, nil)
	step := mat.NewVecDense(nDim, nil)

	// Draw a random number of steps to take.
	nSteps := 1 + rnd.Intn(100)
	for i := 0; i < nSteps; i++ {
		// Draw a random step and update the position.
		dist.UnitVecTo(step)
		position.AddVec(position, step)
	}

	// Finally compute distance from the origin.
	distance := mat.Norm(position, 2)
	fmt.Printf("took %d steps in %d-space, walked %1.1f in total", nSteps, nDim, distance)
}

Output:

took 22 steps in 52-space, walked 5.3 in total

func NewUnitVector

func NewUnitVector(src rand.Source) *UnitVector

NewUnitVector constructs a unit vector generator.

func (*UnitVector) UnitVecTo

func (u *UnitVector) UnitVecTo(dst *mat.VecDense)

UnitVecTo sets dst to be a random unit-length vector.

This uses the algorithm of Mueller from: https://dl.acm.org/doi/10.1145/377939.377946 and summarized at: https://mathworld.wolfram.com/HyperspherePointPicking.html

UnitVecTo panics if dst has 0 length.

type Wishart

type Wishart struct {
	// contains filtered or unexported fields
}

Wishart is a distribution over d×d positive symmetric definite matrices. It is parametrized by a scalar degrees of freedom parameter ν and a d×d positive definite matrix V.

The Wishart PDF is given by

p(X) = [|X|^((ν-d-1)/2) * exp(-tr(V^-1 * X)/2)] / [2^(ν*d/2) * |V|^(ν/2) * Γ_d(ν/2)]

where X is a d×d PSD matrix, ν > d-1, |·| denotes the determinant, tr is the trace and Γ_d is the multivariate gamma function.

See https://en.wikipedia.org/wiki/Wishart_distribution for more information.

func NewWishart

func NewWishart(v mat.Symmetric, nu float64, src rand.Source) (*Wishart, bool)

NewWishart returns a new Wishart distribution with the given shape matrix and degrees of freedom parameter. NewWishart returns whether the creation was successful.

NewWishart panics if nu <= d - 1 where d is the order of v.

func (*Wishart) LogProbSym

func (w *Wishart) LogProbSym(x mat.Symmetric) float64

LogProbSym returns the log of the probability of the input symmetric matrix.

LogProbSym returns -∞ if the input matrix is not positive definite (the Cholesky decomposition fails).

func (*Wishart) LogProbSymChol

func (w *Wishart) LogProbSymChol(cholX *mat.Cholesky) float64

LogProbSymChol returns the log of the probability of the input symmetric matrix given its Cholesky decomposition.

func (*Wishart) MeanSymTo

func (w *Wishart) MeanSymTo(dst *mat.SymDense)

MeanSymTo calculates the mean matrix of the distribution in and stores it in dst. If dst is empty, it is resized to be an d×d symmetric matrix where d is the order of the receiver. When dst is non-empty, MeanSymTo panics if dst is not d×d.

func (*Wishart) ProbSym

func (w *Wishart) ProbSym(x mat.Symmetric) float64

ProbSym returns the probability of the symmetric matrix x. If x is not positive definite (the Cholesky decomposition fails), it has 0 probability.

func (*Wishart) RandCholTo

func (w *Wishart) RandCholTo(dst *mat.Cholesky)

RandCholTo generates the Cholesky decomposition of a random matrix from the distribution. If dst is empty, it is resized to be an d×d symmetric matrix where d is the order of the receiver. When dst is non-empty, RandCholTo panics if dst is not d×d.

func (*Wishart) RandSymTo

func (w *Wishart) RandSymTo(dst *mat.SymDense)

RandSymTo generates a random symmetric matrix from the distribution. If dst is empty, it is resized to be an d×d symmetric matrix where d is the order of the receiver. When dst is non-empty, RandSymTo panics if dst is not d×d.