samplemv

Documentation

Overview

Package samplemv implements advanced sampling routines from explicit and implicit probability distributions.

Each sampling routine is implemented as a stateless function with a complementary wrapper type. The wrapper types allow the sampling routines to implement interfaces.

Index

• Variables
• func IID(batch *mat64.Dense, d distmv.Rander)
• func Importance(batch *mat64.Dense, weights []float64, target distmv.LogProber, ...)
• func LatinHypercube(batch *mat64.Dense, q distmv.Quantiler, src *rand.Rand)
• func MetropolisHastings(batch *mat64.Dense, initial []float64, target distmv.LogProber, ...)
• func Rejection(batch *mat64.Dense, target distmv.LogProber, proposal distmv.RandLogProber, ...) (nProposed int, ok bool)
• type IIDer
  • func (iid IIDer) Sample(batch *mat64.Dense)
• type Importancer
  • func (l Importancer) SampleWeighted(batch *mat64.Dense, weights []float64)
• type LatinHypercuber
  • func (l LatinHypercuber) Sample(batch *mat64.Dense)
• type MHProposal
• type MetropolisHastingser
  • func (m MetropolisHastingser) Sample(batch *mat64.Dense)
• type ProposalNormal
  • func NewProposalNormal(sigma *mat64.SymDense, src *rand.Rand) (*ProposalNormal, bool)
  • func (p *ProposalNormal) ConditionalLogProb(x, y []float64) (prob float64)
  • func (p *ProposalNormal) ConditionalRand(x, y []float64) []float64
• type Rejectioner
  • func (r *Rejectioner) Err() error
  • func (r *Rejectioner) Proposed() int
  • func (r *Rejectioner) Sample(batch *mat64.Dense)
• type SampleUniformWeighted
  • func (w SampleUniformWeighted) SampleWeighted(batch *mat64.Dense, weights []float64)
• type Sampler
• type WeightedSampler

Variables

var ErrRejection = errors.New("rejection: acceptance ratio above 1")

ErrRejection is returned when the constant in Rejection is not sufficiently high.

Functions

func IID

func IID(batch *mat64.Dense, d distmv.Rander)

IID generates a set of independently and identically distributed samples from the input distribution.

func Importance

func Importance(batch *mat64.Dense, weights []float64, target distmv.LogProber, proposal distmv.RandLogProber)

Importance sampling generates rows(batch) samples from the proposal distribution, and stores the locations and importance sampling weights in place.

Importance sampling is a variance reduction technique where samples are generated from a proposal distribution, q(x), instead of the target distribution p(x). This allows relatively unlikely samples in p(x) to be generated more frequently.

The importance sampling weight at x is given by p(x)/q(x). To reduce variance, a good proposal distribution will bound this sampling weight. This implies the support of q(x) should be at least as broad as p(x), and q(x) should be "fatter tailed" than p(x).

If weights is nil, the weights are not stored. The length of weights must equal the length of batch, otherwise Importance will panic.

func LatinHypercube

func LatinHypercube(batch *mat64.Dense, q distmv.Quantiler, src *rand.Rand)

LatinHypercube generates rows(batch) samples using Latin hypercube sampling from the given distribution. If src is not nil, it will be used to generate random numbers, otherwise rand.Float64 will be used.

Latin hypercube sampling divides the cumulative distribution function into equally spaced bins and guarantees that one sample is generated per bin. Within each bin, the location is randomly sampled. The distmv.NewUnitUniform function can be used for easy sampling from the unit hypercube.

func MetropolisHastings

func MetropolisHastings(batch *mat64.Dense, initial []float64, target distmv.LogProber, proposal MHProposal, src *rand.Rand)

MetropolisHastings generates rows(batch) samples using the Metropolis Hastings algorithm (http://en.wikipedia.org/wiki/Metropolis%E2%80%93Hastings_algorithm), with the given target and proposal distributions, starting at the intial location and storing the results in-place into samples. If src != nil, it will be used to generate random numbers, otherwise rand.Float64 will be used.

Metropolis-Hastings is a Markov-chain Monte Carlo algorithm that generates samples according to the distribution specified by target by using the Markov chain implicitly defined by the proposal distribution. At each iteration, a proposal point is generated randomly from the current location. This proposal point is accepted with probability

p = min(1, (target(new) * proposal(current|new)) / (target(current) * proposal(new|current)))

If the new location is accepted, it is stored into batch and becomes the new current location. If it is rejected, the current location remains and is stored into samples. Thus, a location is stored into batch at every iteration.

The samples in Metropolis Hastings are correlated with one another through the Markov chain. As a result, the initial value can have a significant influence on the early samples, and so, typically, the first samples generated by the chain are ignored. This is known as "burn-in", and can be accomplished with slicing. The best choice for burn-in length will depend on the sampling and target distributions.

Many choose to have a sampling "rate" where a number of samples are ignored in between each kept sample. This helps decorrelate the samples from one another, but also reduces the number of available samples. A sampling rate can be implemented with successive calls to MetropolisHastings.

func Rejection

func Rejection(batch *mat64.Dense, target distmv.LogProber, proposal distmv.RandLogProber, c float64, src *rand.Rand) (nProposed int, ok bool)

Rejection generates rows(batch) samples using the rejection sampling algorithm and stores them in place into samples. Sampling continues until batch is filled. Rejection returns the total number of proposed locations and a boolean indicating if the rejection sampling assumption is violated (see details below). If the returned boolean is false, all elements of samples are set to NaN. If src != nil, it will be used to generate random numbers, otherwise rand.Float64 will be used.

Rejection sampling generates points from the target distribution by using the proposal distribution. At each step of the algorithm, the proposaed point is accepted with probability

p = target(x) / (proposal(x) * c)

where target(x) is the probability of the point according to the target distribution and proposal(x) is the probability according to the proposal distribution. The constant c must be chosen such that target(x) < proposal(x) * c for all x. The expected number of proposed samples is len(samples) * c.

Target may return the true (log of) the probablity of the location, or it may return a value that is proportional to the probability (logprob + constant). This is useful for cases where the probability distribution is only known up to a normalization constant.

Types

type IIDer

type IIDer struct {
	Dist distmv.Rander
}

IIDer is a wrapper around the IID sample generation method.

func (IIDer) Sample

func (iid IIDer) Sample(batch *mat64.Dense)

Sample generates a set of identically and independently distributed samples.

type Importancer

type Importancer struct {
	Target   distmv.LogProber
	Proposal distmv.RandLogProber
}

Importancer is a wrapper around the Importance sampling generation method.

func (Importancer) SampleWeighted

func (l Importancer) SampleWeighted(batch *mat64.Dense, weights []float64)

SampleWeighted generates rows(batch) samples using the Importance sampling generation procedure.

type LatinHypercuber

type LatinHypercuber struct {
	Q   distmv.Quantiler
	Src *rand.Rand
}

LatinHypercuber is a wrapper around the LatinHypercube sampling generation method.

func (LatinHypercuber) Sample

func (l LatinHypercuber) Sample(batch *mat64.Dense)

Sample generates rows(batch) samples using the LatinHypercube generation procedure.

type MHProposal

type MHProposal interface {
	// ConditionalLogProb returns the probability of the first argument
	// conditioned on being at the second argument.
	//  p(x|y)
	// ConditionalLogProb panics if the input slices are not the same length.
	ConditionalLogProb(x, y []float64) (prob float64)

	// ConditionalRand generates a new random location conditioned being at the
	// location y. If the first arguement is nil, a new slice is allocated and
	// returned. Otherwise, the random location is stored in-place into the first
	// argument, and ConditionalRand will panic if the input slice lengths differ.
	ConditionalRand(x, y []float64) []float64
}

MHProposal defines a proposal distribution for Metropolis Hastings.

type MetropolisHastingser

type MetropolisHastingser struct {
	Initial  []float64
	Target   distmv.LogProber
	Proposal MHProposal
	Src      *rand.Rand

	BurnIn int
	Rate   int
}

MetropolisHastingser is a wrapper around the MetropolisHastings sampling type.

BurnIn sets the number of samples to discard before keeping the first sample. A properly set BurnIn rate will decorrelate the sampling chain from the initial location. The proper BurnIn value will depend on the mixing time of the Markov chain defined by the target and proposal distributions.

Rate sets the number of samples to discard in between each kept sample. A higher rate will better approximate independently and identically distributed samples, while a lower rate will keep more information (at the cost of higher correlation between samples). If Rate is 0 it is defaulted to 1.

The initial value is NOT changed during calls to Sample.

func (MetropolisHastingser) Sample

func (m MetropolisHastingser) Sample(batch *mat64.Dense)

Sample generates rows(batch) samples using the Metropolis Hastings sample generation method. The initial location is NOT updated during the call to Sample.

The number of columns in batch must equal len(m.Initial), otherwise Sample will panic.

type ProposalNormal

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

ProposalNormal is a sampling distribution for Metropolis-Hastings. It has a fixed covariance matrix and changes the mean based on the current sampling location.

func NewProposalNormal

func NewProposalNormal(sigma *mat64.SymDense, src *rand.Rand) (*ProposalNormal, bool)

NewProposalNormal constructs a new ProposalNormal for use as a proposal distribution for Metropolis-Hastings. ProposalNormal is a multivariate normal distribution (implemented by distmv.Normal) where the covariance matrix is fixed and the mean of the distribution changes.

NewProposalNormal returns {nil, false} if the covariance matrix is not positive-definite.

func (*ProposalNormal) ConditionalLogProb

func (p *ProposalNormal) ConditionalLogProb(x, y []float64) (prob float64)

ConditionalLogProb returns the probability of the first argument conditioned on being at the second argument.

p(x|y)

ConditionalLogProb panics if the input slices are not the same length or are not equal to the dimension of the covariance matrix.

func (*ProposalNormal) ConditionalRand

func (p *ProposalNormal) ConditionalRand(x, y []float64) []float64

ConditionalRand generates a new random location conditioned being at the location y. If the first arguement is nil, a new slice is allocated and returned. Otherwise, the random location is stored in-place into the first argument, and ConditionalRand will panic if the input slice lengths differ or if they are not equal to the dimension of the covariance matrix.

type Rejectioner

type Rejectioner struct {
	C        float64
	Target   distmv.LogProber
	Proposal distmv.RandLogProber
	Src      *rand.Rand
	// contains filtered or unexported fields
}

Rejectioner is a wrapper around the Rejection sampling generation procedure. If the rejection sampling fails during the call to Sample, all samples will be set to math.NaN() and a call to Err will return a non-nil value.

func (*Rejectioner) Err

func (r *Rejectioner) Err() error

Err returns nil if the most recent call to sample was successful, and returns ErrRejection if it was not.

func (*Rejectioner) Proposed

func (r *Rejectioner) Proposed() int

Proposed returns the number of samples proposed during the most recent call to Sample.

func (*Rejectioner) Sample

func (r *Rejectioner) Sample(batch *mat64.Dense)

Sample generates rows(batch) using the Rejection sampling generation procedure. Rejection sampling may fail if the constant is insufficiently high, as described in the function comment for Rejection. If the generation fails, the samples are set to math.NaN(), and a call to Err will return a non-nil value.

type SampleUniformWeighted

type SampleUniformWeighted struct {
	Sampler
}

SampleUniformWeighted wraps a Sampler type to create a WeightedSampler where all weights are equal.

func (SampleUniformWeighted) SampleWeighted

func (w SampleUniformWeighted) SampleWeighted(batch *mat64.Dense, weights []float64)

SampleWeighted generates rows(batch) samples from the embedded Sampler type and sets all of the weights equal to 1. If rows(batch) and len(weights) of weights are not equal, SampleWeighted will panic.

type Sampler

type Sampler interface {
	Sample(batch *mat64.Dense)
}

Sampler generates a batch of samples according to the rule specified by the implementing type. The number of samples generated is equal to rows(batch), and the samples are stored in-place into the input.

type WeightedSampler

type WeightedSampler interface {
	SampleWeighted(batch *mat64.Dense, weights []float64)
}

WeightedSampler generates a batch of samples and their relative weights according to the rule specified by the implementing type. The number of samples generated is equal to rows(batch), and the samples and weights are stored in-place into the inputs. The length of weights must equal rows(batch), otherwise SampleWeighted will panic.