API/Reference

NestedModel(loglike, prior_transform)
NestedModel(loglike, priors::AbstractVector{<:Distribution})

loglike must be callable with a signature loglike(::AbstractVector) where the length of the vector must match the number of parameters in your model.

prior_transform must be a callable with a signature prior_transform(::AbstractVector) that returns the transformation from the unit-cube to parameter space. This is effectively the quantile or ppf of a statistical distribution. For convenience, if a vector of Distribution is provided (as a set of priors), a transformation function will automatically be constructed using Distributions.quantile.

Note: loglike is the only function used for likelihood calculations. This means if you want your priors to be used for the likelihood calculations they must be manually included in the loglike function.

Nested(ndims, nactive;
    bounds=Bounds.MultiEllipsoid,
    proposal=:auto,
    enlarge=1.25,
    update_interval=default_update_interval(proposal, ndims),
    min_ncall=2nactive,
    min_eff=0.10)

Static nested sampler with nactive active points and ndims parameters.

ndims is equivalent to the number of parameters to fit, which defines the dimensionality of the prior volume used in evidence sampling. nactive is the number of live or active points in the prior volume. This is a static sampler, so the number of live points will be constant for all of the sampling.

Bounds and Proposals

bounds declares the Type of Bounds.AbstractBoundingSpace to use in the prior volume. The available bounds are described by Bounds. proposal declares the algorithm used for proposing new points. The available proposals are described in Proposals. If proposal is :auto, will choose the proposal based on ndims

• ndims < 10 - Proposals.Rejection
• 10 ≤ ndims ≤ 20 - Proposals.RWalk
• ndims > 20 - Proposals.Slice

The original nested sampling algorithm is roughly equivalent to using Bounds.Ellipsoid with Proposals.Rejection. The MultiNest algorithm is roughly equivalent to Bounds.MultiEllipsoid with Proposals.Rejection. The PolyChord algorithm is roughly equivalent to using Proposals.RSlice.

Other Parameters

• enlarge - When fitting the bounds to live points, they will be enlarged (in terms of volume) by this linear factor.
• update_interval - How often to refit the live points with the bounds as a fraction of nactive. By default this will be determined using default_update_interval for the given proposal
  • Proposals.Rejection - 1.5
  • Proposals.RWalk and Proposals.RStagger - 0.15 * walks
  • Proposals.Slice - 0.9 * ndims * slices
  • Proposals.RSlice - 2 * slices
• min_ncall: The minimum number of iterations before fitting the first bound; used to

avoid shrinking the bounds before burn-in is completed. By default 2*nactive.

• min_eff: Minimum efficiency (samples accepted / samples generated) before fitting the

first bound; used to avoid shrinking the bounds before burn-in is completed By default 0.1.

NestedSamplers.Bounds

This module contains the different algorithms for bounding the prior volume.

The available implementations are

• Bounds.NoBounds - no bounds on the prior volume (equivalent to a unit cube)
• Bounds.Ellipsoid - bound using a single ellipsoid
• Bounds.MultiEllipsoid - bound using multiple ellipsoids in an optimal cluster

Bounds.AbstractBoundingSpace{T<:Number}

Abstract type for describing the bounding algorithms. For information about the interface, see the extended help (??Bounds.AbstractBoundingSpace)

Extended Help

Interface

The following functionality defines the interface for AbstractBoundingSpace for an example type ::MyBounds

Bounds.NoBounds([T=Float64], N)

Unbounded prior volume; equivalent to the unit cube in N dimensions. This matches the original nested sampling derivation in Skilling (2004).^[1]

Bounds.Ellipsoid([T=Float64], N)
Bounds.Ellipsoid(center::AbstractVector, A::AbstractMatrix)

An N-dimensional ellipsoid defined by

\[(x - center)^T A (x - center) = 1\]

where size(center) == (N,) and size(A) == (N,N).

This implementation follows the algorithm presented in Mukherjee et al. (2006).^[2]

Bounds.MultiEllipsoid([T=Float64], ndims)
Bounds.MultiEllipsoid(::AbstractVector{Ellipsoid})

Use multiple Ellipsoids in an optimal clustering to bound prior space. This implementation follows the MultiNest implementation outlined in Feroz et al. (2008,2009).^[3][4] For more details about the bounding algorithm, see the extended help (??Bounds.MultiEllipsoid)

Extended help

The multiple-ellipsoidal implementation is defined as follows:

1. Fit a Bounds.Ellipsoid to the sample.
2. Perform K-means clustering (here using Clustering.jl) centered at the endpoints of the bounding ellipsoid. This defines two clusters within the sample.
3. If either cluster has fewer than two points, consider it ill-defined and end any recursion.
4. Fit Bounds.Ellipsoid to each of the clusters assigned in (2).
5. If the volume of the parent ellipsoid is more than twice the volume of the two child ellipsoids, recurse (1-5) to each child.

To sample from this distribution, a random ellipsoid is selected, and a random sample is sampled from that ellipsoid. We then reverse this and find all of the ellipsoids which enclose the sampled point, and select one of those randomly for the enclosing bound.

NestedSamplers.Proposals

This module contains the different algorithms for proposing new points within a bounding volume in unit space.

The available implementations are

• Proposals.Rejection - samples uniformly within the bounding volume
• Proposals.RWalk - random walks to a new point given an existing one
• Proposals.RStagger - random staggering away to a new point given an existing one
• Proposals.Slice - slicing away to a new point given an existing one
• Proposals.RSlice - random slicing away to a new point given an existing one

NestedSamplers.AbstractProposal

The abstract type for live point proposal algorithms.

Interface

Each AbstractProposal must have this function,

(::AbstractProposal)(::AbstractRNG, point, loglstar, bounds, loglikelihood, prior_transform)

which, given the input point with loglikelihood loglstar inside a bounds, returns a new point in unit space, prior space, the loglikelihood, and the number of function calls.

Proposals.Rejection(;maxiter=100_000)

Propose a new live point by uniformly sampling within the bounding volume and rejecting samples that do not meet the likelihood constraints. This follows the original nested sampling algorithm proposed in Skilling (2004)^[1]

Parameters

• maxiter is the maximum number of samples that can be rejected before giving up and throwing an error.

Proposals.RWalk(;ratio=0.5, walks=25, scale=1)

Propose a new live point by random walking away from an existing live point. This follows the algorithm outlined in Skilling (2006).^[5]

Parameters

• ratio is the target acceptance ratio
• walks is the minimum number of steps to take
• scale is the proposal distribution scale, which will update between proposals.

Proposals.RStagger(;ratio=0.5, walks=25, scale=1)

Propose a new live point by random staggering away from an existing live point. This differs from the random walk proposal in that the step size here is exponentially adjusted to reach a target acceptance rate during each proposal, in addition to between proposals. This follows the algorithm outlined in Skilling (2006).^[5]

Parameters

• ratio is the target acceptance ratio
• walks is the minimum number of steps to take
• scale is the proposal distribution scale, which will update between proposals.

Proposals.Slice(;slices=5, scale=1)

Propose a new live point by a series of random slices away from an existing live point. This is a standard Gibbs-like implementation where a single multivariate slice is a combination of slices univariate slices through each axis. This follows the algorithm outlined in Neal (2003).^[6]

Parameters

• slices is the minimum number of slices
• scale is the proposal distribution scale, which will update between proposals.

Proposals.RSlice(;slices=5, scale=1)

Propose a new live point by a series of random slices away from an existing live point. This is a standard random implementation where each slice is along a random direction based on the provided axes. This more closely matches the PolyChord implementation outlined in Handley et al. (2015a,b).^[7][8]

Parameters

• slices is the minimum number of slices
• scale is the proposal distribution scale, which will update between proposals.

This module contains various statistical models in the form of NestedModels. These models can be used for examples and for testing.

• Models.GaussianShells
• Models.CorrelatedGaussian

Models.GaussianShells()

2-D Gaussian shells centered at [-3.5, 0] and [3.5, 0] with a radius of 2 and a shell width of 0.1

Examples

julia> model, lnZ = Models.GaussianShells();

julia> lnZ
-1.75

Models.CorrelatedGaussian(ndims)

Creates a highly-correlated Gaussian with the given dimensionality.

\[\mathbf\theta \sim \mathcal{N}\left(2\mathbf{1}, \mathbf{I}\right)\]

\[\Sigma_{ij} = \begin{cases} 1 &\quad i=j \\ 0.95 &\quad i\neq j \end{cases}\]

\[\mathcal{L}(\mathbf\theta) = \mathcal{N}\left(\mathbf\theta | \mathbf{0}, \mathbf\Sigma \right)\]

the analytical evidence of the model is

\[Z = \mathcal{N}\left(2\mathbf{1} | \mathbf{0}, \mathbf\Sigma + \mathbf{I} \right)\]

Examples

julia> model, lnZ = Models.CorrelatedGaussian(10);

julia> lnZ
-12.482738597926607

Models.Eggbox()

Eggbox/Egg carton likelihood function

\[z(x, y) = \left[a + \cos\frac{x}{b} \cdot \cos\frac{x}{b} \right]^5\]

Examples

julia> model, lnZ = Models.Eggbox();

julia> lnZ
235.88