Internal API

Note

This is the documentation of BAT's internal API. The internal API is fully accessible to users, but all aspects of it are subject to change without deprecation. Functionalities of the internal API that, over time, turn out to require user access (e.g. to support advanced use cases) will be evolved to gain a stable interface and then promoted to the public API.

Types

Functions and macros

Documentation

BAT.AbstractMeasureOrDensityType
abstract type AbstractMeasureOrDensity

BAT-internal, not part of stable public API.

Subtypes of AbstractMeasureOrDensity must be implement the function

  • DensityInterface.logdensityof(density::SomeDensity, v)

For likelihood densities this is typically sufficient, since BAT can infer variate shape and bounds from the prior.

Note

If DensityInterface.logdensityof is called with an argument that is out of bounds, the behavior is undefined. The result for arguments that are not within bounds is implicitly -Inf, but it is the caller's responsibility to handle these cases.

source
BAT.AbstractProposalDistType
abstract type AbstractProposalDist

BAT-internal, not part of stable public API.

The following functions must be implemented for subtypes:

  • BAT.proposaldist_logpdf
  • BAT.proposal_rand!
  • LinearAlgebra.issymmetric, indicating whether p(a -> b) == p(b -> a) holds true.
source
BAT.AbstractSampleGeneratorType
abstract type AbstractSampleGenerator

BAT-internal, not part of stable public API.

Abstract super type for sample generators.

source
BAT.AnyIIDSampleableType
BAT.AnyIIDSampleable = Union{...}

BAT-internal, not part of stable public API.

Union of all distribution/density-like types that BAT can draw i.i.d. (independent and identically distributed) samples from:

source
BAT.AnyMeasureOrDensityType
BAT.AnyMeasureOrDensity = Union{...}

BAT-internal, not part of stable public API.

Union of all types that BAT will accept as a probability density, resp. that convert(AbstractMeasureOrDensity, d) supports:

source
BAT.BasicMvStatisticsType
BasicMvStatistics{T<:Real,W}

BAT-internal, not part of stable public API.

W must either be Weights (no bias correction) or one of AnalyticWeights, FrequencyWeights or ProbabilityWeights to specify the desired bias correction method.

source
BAT.CholeskyPartialWhiteningType
struct CholeskyPartialWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

Whitening transformation based on a Cholesky transformation of the empirical sample covariance matrix.

Only transforms dimensions (degrees of freedom) for which the marginalized distribution asymptotically approaches zero in the positive and negative direction.

Constructors:

  • CholeskyPartialWhitening()
source
BAT.CholeskyWhiteningType
struct CholeskyWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

Whitening transformation based on a Cholesky transformation of the empirical sample covariance matrix.

Constructors:

  • CholeskyWhitening()
source
BAT.DistLikeMeasureType
abstract type DistLikeMeasure <: BATMeasure

BAT-internal, not part of stable public API.

A density that implements part of the Distributions.Distribution interface. Such densities are suitable for use as a priors.

Typically, custom priors should be implemented as subtypes of Distributions.Distribution. BAT will automatically wrap them in a subtype of DistLikeMeasure.

Subtypes of DistLikeMeasure are required to support more functionality than an AbstractMeasureOrDensity, but less than a Distribution{Multivariate,Continuous}.

A d::Distribution{Multivariate,Continuous} can be converted into (wrapped in) an DistLikeMeasure via conv(DistLikeMeasure, d).

The following functions must be implemented for subtypes:

  • DensityInterface.logdensityof

  • Distributions.sampler

  • Statistics.cov

  • BAT.var_bounds

Note

The function BAT.var_bounds is not part of the stable public BAT-API and subject to change without deprecation.

source
BAT.ENSAutoProposalType
struct BAT.ENSAutoProposal <: ENSProposal

Experimental feature, not part of stable public API.

Choose the proposal depending from the number of dimensions: ndims < 10: Proposals.Uniform, 10 ≤ ndims ≤ 20: Proposals.RWalk, ndims > 20: Proposals.Slice

source
BAT.ENSBoundType
abstract type ENSBound

Experimental feature, not part of stable public API.

Abstract type for the bounds of the sampling region used by EllipsoidalNestedSampling.

source
BAT.ENSEllipsoidBoundType
struct BAT.ENSEllipsoidBound <: ENSBound

Experimental feature, not part of stable public API.

Ellipsoid bound means that a n-dimensional ellipsoid limits the sampling volume.

source
BAT.ENSMultiEllipsoidBoundType
struct BAT.ENSMultiEllipsoidBound <: ENSBound

Experimental feature, not part of stable public API.

Multi ellipsoid bound means that there are multiple elliposid in an optimal clustering are used to limit the sampling volume.

source
BAT.ENSNoBoundsType
struct BAT.ENSNoBounds <: ENSBound

Experimental feature, not part of stable public API.

No bounds means that the whole volume from the unit Cube is used to find new points.

source
BAT.ENSProposalType
abstract type ENSProposal

Experimental feature, not part of stable public API.

Abstract type for the algorithms to propose new live points used used by EllipsoidalNestedSampling.

source
BAT.ENSRandomWalkType
struct BAT.ENSRandomWalk <: ENSProposal

Experimental feature, not part of stable public API.

New live point is proposed by using a random walk away from an existing live point.

Constructors:

  • ENSRandomWalk(; fields...)

Fields:

  • ratio::Float64: Acceptance ratio for the random walk. Default: 0.5

  • walks::Int64: Minimum number of random walk steps. Default: 25

  • scale::Float64: Scale of the proposal distribution. Default: 1.0

source
BAT.ENSSliceType
struct BAT.ENSSlice <: ENSProposal

Experimental feature, not part of stable public API.

New live point is proposed by a serie of random slices from an existing live-point.

Constructors:

  • ENSSlice(; fields...)

Fields:

  • slices::Int64: Minimum number of slices Default: 5

  • scale::Float64: Scale of the proposal distribution. Default: 1.0

source
BAT.ENSUniformlyType
struct BAT.ENSUniformly <: ENSProposal

Experimental feature, not part of stable public API.

Each point in the bounding volume has an uniform chance to be proposed as a new live point.

source
BAT.FullMeasureTransformType
struct FullMeasureTransform <: TransformAlgorithm

BAT-internal, not part of stable public API.

Transform the density as a whole a given specified target space. Operations that use the gradient of the density will require to the log(abs(jacobian)) of the transformation to be auto-differentiable.

Constructors:

  • FullMeasureTransform()
source
BAT.LFDensityType
struct BAT.LFDensity{F}

BAT-internal, not part of stable public API.

Wraps a log-density function log_f.

source
BAT.LFDensityWithGradType
BAT.LFDensityWithGrad{F,G} <: BATDensity

BAT-internal, not part of stable public API.

Constructors:

LFDensityWithGrad(logf, valgradlogf)

A density defined by a function that computes it's logarithmic value at given points, as well as a function that computes both the value and the gradient.

It must be safe to execute both functions in parallel on multiple threads and processes.

source
BAT.LogDValType
struct LogDVal{T<:Real}

LogDVal is deprecated and will be removed in future major or even minor BAT versions.

source
BAT.MCMCIteratorType
abstract type MCMCIterator end

BAT-internal, not part of stable public API.

Represents the current state of an MCMC chain.

Note

The details of the MCMCIterator and MCMCAlgorithm API (see below) currently do not form part of the stable API and are subject to change without deprecation.

To implement a new MCMC algorithm, subtypes of both MCMCAlgorithm and MCMCIterator are required.

The following methods must be defined for subtypes of MCMCIterator (e.g. SomeMCMCIter<:MCMCIterator):

BAT.getalgorithm(chain::SomeMCMCIter)::MCMCAlgorithm

BAT.getmeasure(chain::SomeMCMCIter)::AbstractMeasureOrDensity

BAT.get_context(chain::SomeMCMCIter)::BATContext

BAT.mcmc_info(chain::SomeMCMCIter)::MCMCIteratorInfo

BAT.nsteps(chain::SomeMCMCIter)::Int

BAT.nsamples(chain::SomeMCMCIter)::Int

BAT.current_sample(chain::SomeMCMCIter)::DensitySample

BAT.sample_type(chain::SomeMCMCIter)::Type{<:DensitySample}

BAT.samples_available(chain::SomeMCMCIter, nonzero_weights::Bool = false)::Bool

BAT.get_samples!(samples::DensitySampleVector, chain::SomeMCMCIter, nonzero_weights::Bool)::typeof(samples)

BAT.next_cycle!(chain::SomeMCMCIter)::SomeMCMCIter

BAT.mcmc_step!(
    chain::SomeMCMCIter
    callback::Function,
)::nothing

The following methods are implemented by default:

getalgorithm(chain::MCMCIterator)
getmeasure(chain::MCMCIterator)
DensitySampleVector(chain::MCMCIterator)
mcmc_iterate!(chain::MCMCIterator, ...)
mcmc_iterate!(chains::AbstractVector{<:MCMCIterator}, ...)
isvalidchain(chain::MCMCIterator)
isviablechain(chain::MCMCIterator)
source
BAT.MCMCSampleGeneratorType
BAT.MCMCSampleGenerator

BAT-internal, not part of stable public API.

MCMC sample generator.

Constructors:

MCMCSampleGenerator(chain::AbstractVector{<:MCMCIterator})
source
BAT.NoWhiteningType
struct NoWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

No-op whitening transformation, leaves samples unchanged.

Constructors:

  • NoWhitening()
source
BAT.OnlineMvCovType
OnlineMvCov{T<:AbstractFloat,W} <: AbstractMatrix{T}

BAT-internal, not part of stable public API.

Implementation based on variance calculation Algorithms of Welford and West.

W must either be Weights (no bias correction) or one of AnalyticWeights, FrequencyWeights or ProbabilityWeights to specify the desired bias correction method.

source
BAT.OnlineMvMeanType
OnlineMvMean{T<:AbstractFloat} <: AbstractVector{T}

BAT-internal, not part of stable public API.

Multivariate mean implemented via Kahan-Babuška-Neumaier summation.

source
BAT.OnlineUvMeanType
OnlineUvMean{T<:AbstractFloat}

BAT-internal, not part of stable public API.

Univariate mean implemented via Kahan-Babuška-Neumaier summation.

source
BAT.OnlineUvVarType
OnlineUvVar{T<:AbstractFloat,W}

BAT-internal, not part of stable public API.

Implementation based on variance calculation Algorithms of Welford and West.

W must either be Weights (no bias correction) or one of AnalyticWeights, FrequencyWeights or ProbabilityWeights to specify the desired bias correction method.

source
BAT.RenormalizedType
struct Renormalized <: AbstractMeasureOrDensity

BAT-internal, not part of stable public API.

Constructors:

  • Renormalized(density::AbstractMeasureOrDensity, logrenormf::Real)

A renormalized density derived from density, with

logdensityof(Renormalized(density, logrenormf))(v) ==
    logdensityof(density)(v) + logrenormf
source
BAT.StandardMvNormalType
StandardMvNormal{T<:Real} <: Distributions.AbstractMvNormal

A standard n-dimensional multivariate normal distribution with it's mean at the origin and an identity covariance matrix.

Constructor:

    StandardMvNormal(n::Integer)
    StandardMvNormal{T<:Real}(n::Integer)
source
BAT.StandardMvUniformType
StandardMvUniform{T<:Real} <: Distributions.Distribution{Multivariate,Continuous}

A standard n-dimensional multivariate uniform distribution, from zero to one in each dimension.

Constructor:

    StandardMvUniform(n::Integer)
    StandardMvUniform{T<:Real}(n::Integer)
source
BAT.StandardUvNormalType
StandardUvNormal{T<:Real} <: Distributions.Distribution{Univariate,Continuous}

A standard normal distribution with a mean of zero and a variance of one.

Constructor:

    StandardUvNormal()
    StandardUvNormal{T<:Real}()
source
BAT.StandardUvUniformType
StandardUvUniform{T<:Real} <: Distributions.Distribution{Univariate,Continuous}

A standard uniform distribution between zero and one.

Constructor:

    StandardUvUniform()
    StandardUvUniform{T<:Real}()
source
BAT.StatisticalWhiteningType
struct StatisticalWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

Whitening transformation based statistical whitening. CholeskyPartialWhitening

Constructors:

  • StatisticalWhitening()
source
BAT.WhiteningAlgorithmType
abstract type WhiteningAlgorithm

BAT-internal, not part of stable public API.

Abstract type for sample whitening algorithms.

source
BAT.WrappedNonBATDensityType
struct BAT.WrappedNonBATDensity{F<:Base.Callable}

BAT-internal, not part of stable public API.

Wraps a log-density function log_f.

source
BAT.trafoofFunction
trafoof(d::Transformed)::AbstractMeasureOrDensity

Get the transform from parent(d) to d, so that

trafoof(d)(parent(d)) == d
source
BAT.logvalofFunction
logvalof(r::NamedTuple{(...,:log,...)})::Real
logvalof(r::LogDVal)::Real

BAT-internal, not part of stable public API.

source
BAT.fft_autocorFunction
fft_autocor(v::AbstractVector{<:Real})
fft_autocor(v::AbstractVectorOfSimilarVectors{<:Real})

BAT-internal, not part of stable public API.

Compute the autocorrelation function (ACF) of variate series v, separately for each degree of freedom.

Uses FFT, in contract to StatsBase.autocor.

source
BAT.fft_autocovFunction
fft_autocov(v::AbstractVector{<:Real})
fft_autocov(v::AbstractVectorOfSimilarVectors{<:Real})

BAT-internal, not part of stable public API.

Compute the autocovariance of of variate series v, separately for each degree of freedom.

Uses FFT, in contract to StatsBase.autocov.

source
BAT.argchoice_msgFunction
argchoice_msg(f::Base.Callable, argname::Val, x)

BAT-internal, not part of stable public API.

Generates an information message regarding the choice of value x for argument argname of function f.

The value x will often be the result of bat_default.

source
BAT.bat_samplerFunction
bat_sampler(d::Distribution)

BAT-internal, not part of stable public API.

Tries to return a BAT-compatible sampler for Distribution d. A sampler is BAT-compatible if it supports random number generation using an arbitrary AbstractRNG:

rand(rng::AbstractRNG, s::SamplerType)
rand!(rng::AbstractRNG, s::SamplerType, x::AbstractArray)

If no specific method of bat_sampler is defined for the type of d, it will default to sampler(d), which may or may not return a BAT-compatible sampler.

source
BAT.bg_R_2sqrFunction
bg_R_2sqr(stats::AbstractVector{<:MCMCBasicStats}; corrected::Bool = false)
bg_R_2sqr(samples::AbstractVector{<:DensitySampleVector}; corrected::Bool = false)

BAT-internal, not part of stable public API.

Brooks-Gelman R_2^2 for all DOF. If normality is assumed, 'corrected' should be set to true to account for the sampling variability.

source
BAT.checked_logdensityofFunction
checked_logdensityof(density::AbstractMeasureOrDensity, v::Any, T::Type{<:Real})

BAT-internal, not part of stable public API.

Evaluates density log-value via DensityInterface.logdensityof and performs additional checks.

Throws a BAT.EvalException on any of these conditions:

  • The variate shape of density (if known) does not match the shape of v.
  • The return value of DensityInterface.logdensityof is NaN.
  • The return value of DensityInterface.logdensityof is an equivalent of positive infinity.
source
BAT.default_val_numtypeFunction
BAT.default_val_numtype(density::AbstractMeasureOrDensity)

BAT-internal, not part of stable public API.

Returns the default/preferred numerical type (log-)density values of density.

source
BAT.default_var_numtypeFunction
BAT.default_var_numtype(density::AbstractMeasureOrDensity)

BAT-internal, not part of stable public API.

Returns the default/preferred underlying numerical type for (elements of) variates of density.

source
BAT.density_valtypeFunction
BAT.density_valtype(density::AbstractMeasureOrDensity, v::Any)

BAT-internal, not part of stable public API.

Determine a suitable return type for the (log-)density value of the given density for the given variate.

source
BAT.drop_low_weight_samplesFunction
drop_low_weight_samples(
    samples::DensitySampleVector,
    fraction::Real = 10^-4
)

BAT-internal, not part of stable public API.

Drop fraction of the total probability mass from samples to filter out the samples with the lowest weight.

source
BAT.find_marginalmodesFunction
find_marginalmodes(marg::MarginalDist)

BAT-internal, not part of stable public API.

Find the modes of a MarginalDist. Returns a vector of the bin-centers of the bin(s) with the heighest weight.

source
BAT.fromuhcFunction
fromuhc(X::AbstractVector, vol::SpatialVolume)
fromuhc(X::VectorOfSimilarVectors, vol::SpatialVolume)

BAT-internal, not part of stable public API.

Bijective transformation from unit hypercube to vol. See fromuhc!.

Use inv(fromuhc) to get the the inverse transformation.

source
BAT.fromuhc!Function
fromuhc!(Y::AbstractVector, X::AbstractVector, vol::SpatialVolume)
fromuhc!(Y::VectorOfSimilarVectors, X::VectorOfSimilarVectors, vol::SpatialVolume)

BAT-internal, not part of stable public API.

Bijective transformation of coordinates X within the unit hypercube to coordinates Y in vol. If X and Y are matrices, the transformation is applied to the column vectors. Use Y === X to transform in-place.

Use inv(fromuhc!) to get the the inverse transformation.

source
BAT.fromuiFunction
y = fromui(x::Real, lo::Real, hi::Real)
y = fromui(x::Real, lo_hi::ClosedInterval{<:Real})

BAT-internal, not part of stable public API.

Linear bijective transformation from the unit inverval (i.e. x ∈ 0..1) to y ∈ lo..hi.

Use inv(fromui) to get the the inverse transformation.

Use @inbounds to disable range checking on the input value.

source
BAT.get_bin_centersFunction
get_bin_centers(marg::MarginalDist)

BAT-internal, not part of stable public API.

Returns a vector of the bin-centers.

source
BAT.getlikelihoodFunction
getlikelihood(posterior::AbstractPosteriorMeasure)::BATDenstiy

BAT-internal, not part of stable public API.

The likelihood density of posterior. The likelihood may or may not be normalized.

source
BAT.getpriorFunction
getprior(posterior::AbstractPosteriorMeasure)::BATMeasure

BAT-internal, not part of stable public API.

The prior density of posterior. The prior may or may not be normalized.

source
BAT.gr_RsqrFunction
gr_Rsqr(stats::AbstractVector{<:MCMCBasicStats})
gr_Rsqr(samples::AbstractVector{<:DensitySampleVector})

BAT-internal, not part of stable public API.

Gelman-Rubin $$R^2$$ for all DOF.

source
BAT.is_log_zeroFunction
BAT.is_log_zero(x::Real, T::Type{<:Real} = typeof(x)}

BAT-internal, not part of stable public API.

Check if x is an equivalent of log of zero, resp. negative infinity, in respect to type T.

source
BAT.issymmetric_around_originFunction
issymmetric_around_origin(d::Distribution)

BAT-internal, not part of stable public API.

Returns true (resp. false) if the Distribution is symmetric (resp. non-symmetric) around the origin.

source
BAT.log_volumeFunction
log_volume(vol::SpatialVolume)

BAT-internal, not part of stable public API.

Get the logarithm of the volume of the space in vol.

source
BAT.log_zero_densityFunction
BAT.log_zero_density(T::Type{<:Real})

log-density value to assume for regions of implicit zero density, e.g. outside of variate/parameter bounds/support.

Returns an equivalent of negative infinity.

source
BAT.proposal_rand!Function
function proposal_rand!(
    rng::AbstractRNG,
    pdist::GenericProposalDist,
    v_proposed::Union{AbstractVector,VectorOfSimilarVectors},
    v_current::Union{AbstractVector,VectorOfSimilarVectors}
)

BAT-internal, not part of stable public API.

Generate one or multiple proposed variate/parameter vectors, based on one or multiple previous vectors.

Input:

  • rng: Random number generator to use
  • pdist: Proposal distribution to use
  • v_current: Old values (vector or column vectors, if a matrix)

Output is stored in

  • v_proposed: New values (vector or column vectors, if a matrix)

The caller must guarantee:

  • size(v_current, 1) == size(v_proposed, 1)
  • size(v_current, 2) == size(v_proposed, 2) or size(v_current, 2) == 1
  • v_proposed !== v_current (no aliasing)

Implementations of proposal_rand! must be thread-safe.

source
BAT.proposaldist_logpdfFunction
proposaldist_logpdf(
    p::AbstractArray,
    pdist::AbstractProposalDist,
    v_proposed::AbstractVector,
    v_current:::AbstractVector
)

BAT-internal, not part of stable public API.

Returns log(PDF) value of pdist for transitioning from current to proposed variate/parameters.

source
BAT.repetition_to_weightsFunction
repetition_to_weights(v::AbstractVector)

BAT-internal, not part of stable public API.

Drop (subsequently) repeated samples by adding weights.

source
BAT.smallest_credible_intervalsFunction
smallest_credible_intervals(
    X::AbstractVector{<:Real}, W::AbstractWeights = UnitWeights(...);
    nsigma_equivalent::Integer = 1
)

BAT-internal, not part of stable public API.

Find smalles credible intervals with nsigma_equivalent of 1, 2 or 3 (containing 68.27%, 9545%, or 0.9973% of the total probability mass).

source
smallest_credible_intervals(smpl::DensitySampleVector{<:AbstractVector{<:Real}}; kwargs...)
source
BAT.spatialvolumeFunction
spatialvolume(b::VarVolumeBounds)::SpatialVolume

BAT-internal, not part of stable public API.

Returns the spatial volume that defines the variate/parameter bounds.

source
BAT.sum_first_dimFunction
@propagate_inbounds sum_first_dim(A::AbstractArray, j::Integer, ks::Integer...)

BAT-internal, not part of stable public API.

Calculate the equivalent of sum(A[:, j, ks...]).

source
@propagate_inbounds sum_first_dim(A::AbstractArray)

BAT-internal, not part of stable public API.

If A is a vector, return sum(A), else sum(A, 1)[:].

source
BAT.trunc_logpdf_ratioFunction
BAT.trunc_logpdf_ratio(orig_dist::Distribution{TP}, trunc_dist::Distribution{TP})::AbstractFloat

BAT-internal, not part of stable public API.

Computes the log-ratio between the amplitude of the PDF of a truncated distribution and the original (untruncted) distribution, within the support of the truncated one.

The PDF of both distributions must have the same shape within the support of trunc_dist and may only differ in amplitude.

Mainly used to implement BAT.truncate_density, in conjunction with BAT.truncate_dist_hard. The result contributes to the logrenormf factor of a [Renormalized] that uses truncated distributions internally, to ensure the density does not get renormalized.

source
BAT.truncate_dist_hardFunction
BAT.truncate_dist_hard(dist::Distribution{Univariate}, bounds::Interval)::Distribution{Univariate}
BAT.truncate_dist_hard(dist::Distribution{Multivariate}, bounds::AbstractArray{<:Interval})::Distribution{Multivariate}

BAT-internal, not part of stable public API.

Generalized variant of Distributions.truncated - also handles multivariate distributions and operates on a best-effort basis: If distributions cannot be truncated, may return the original distribution.

Returns a NamedTuple

    (dist = trunc_dist, logrenormf = logrenormf)

with the truncated distribution and the log-PDF amplitude difference to the original (see BAT.trunc_logpdf_ratio).

Mainly used to implement BAT.truncate_density.

source
BAT.var_boundsFunction
var_bounds(density::DistLikeMeasure)::AbstractVarBounds

BAT-internal, not part of stable public API.

Get the parameter bounds of density. Must not be missing.

source