Experimental features

ARPWeighting{T<:AbstractFloat} <: AbstractMCMCWeightingScheme{T}

Experimental feature, not part of stable public API.

Sample weighting scheme suitable for accept/reject-based sampling algorithms (e.g. RandomWalk). Both accepted and rejected samples become part of the output, with a weight proportional to their original acceptance probability.

Constructors:

• ARPWeighting()

bat_compare(
    samples_1::DensitySampleVector,
    samples_2::DensitySampleVector;
    nsamples::Symbol=:effective
)

Compares two DensitySampleVectors given by samples_1 and samples_2 applying the Kolmogorov-Smirnov test for all marginals.

nsamples specifies how to define a number of samples in the Kolmogorov-Smirnov distribution. The default value is nsamples=:effective, which uses the effective number of samples estimated by bat_eff_sample_size. The optimal keywords:

• :length — length of the DensitySamplesVector is used

• :weights — the sum of the weights is used

Returns a NamedTuple of the shape

(result = X::TypedTables.Table, ...)

bat_integrated_autocorr_len(
    v::_ACLenTarget,
    algorithm::AutocorLenAlgorithm = GeyerAutocorLen(),
    [context::BATContext]
)

Experimental feature, not yet part of stable public API.

Estimate the integrated autocorrelation length of variate series v, separately for each degree of freedom.

Returns a NamedTuple of the shape

(result = integrated_autocorr_len, ...)

Result properties not listed here are algorithm-specific and are not part of the stable public API.

bat_marginalmode(
    target::DensitySampleVector,
    algorithm::AbstractModeEstimator,
    [context::BATContext]
)::DensitySampleVector

Experimental feature, not part of stable public API.

Estimates a marginal mode of target by finding the maximum of marginalized posterior for each dimension.

Returns a NamedTuple of the shape

(result = X::DensitySampleVector, ...)

BAT.auto_renormalize(measure::MeasureBase.AbstractMeasure)

Experimental feature, not part of stable public API.

Returns (result = new_measure, logweight = logweight).

Tries to automatically renormalize measure if a maxium log-m value is available, returns measure unchanged otherwise.

batsampleable(obj)

Experimental feature, not part of stable public API.

Convert obj into something that BAT can sample from.

struct BinnedMarginalModes <: AbstractModeEstimator

Experimental feature, not part of stable public API.

Bin data to estimate modes.

Constructor: BinnedModeEstimator(; fields...)

Fields:

• binning::Any: Default: FreedmanDiaconisBinning()

abstract type DistributionTransform <: Function

Experimental feature, not part of stable public API.

Transform variate values between distributions

Constructors:

DistributionTransform(target_dist, source_dist)
DistributionTransform(Uniform, source_dist)
DistributionTransform(Normal, source_dist)

BAT.enable_error_log(enable::Bool = true)

Experimental feature, not part of stable public API.

Enable/disable BAT's error (exception) log.

The error log is disabled by default.

See BAT.error_log.

BAT.error_log()

Experimental feature, not part of stable public API.

Get a log of certain exceptions throws by BAT, e.g. density evaluation errors.

The error log is disabled by default, use BAT.enable_error_log to enable it.

struct EvalException <: Exception

Constructors:

• EvalException(func::Function, measure::AbstractMeasure, v::Any, ret::Any)

Fields:

• func::Function: Density evaluation function that failed.

• measure::MeasureBase.AbstractMeasure: Density being evaluated.

• v::Any: Variate at which the evaluation of measure (applying f to d at v) failed.

• ret::Any: Cause of failure, either the invalid return value of f on d at v, or another expection (on rethrow).

BAT.ext_default(::PackageExtension{SomePackage}, ::Val{:SomeLabel}, args; kwargs...)

Experimental feature, not part of stable public API.

Returns the default value selected by :SomeLabel within the context of the package extension that depends on SomePackage.

BAT.get_adselector(context::BATContext)

Experimental feature, not yet part of stable public API.

Returns the automatic differentiation selector specified in context.

BAT.get_valid_adselector(context::BATContext, algorithm)

Experimental feature, not yet part of stable public API.

Returns the automatic differentiation selector specified in context, to be used for algorithm.

Throws an exception if context specifies AutoDiffOperators.NoAutoDiff.

abstract type PackageExtension{pkgname}

Experimental feature, not part of stable public API.

Represents a package extension that requires the package pkgname to be loaded.

Do not construct instances of PackageExtension directly, use pkgext(:pkgname) instead which will check that the required extension is active.

BAT.pkgext(:SomePackage)::PackageExtension
BAT.pkgext(Val(:SomePackage))::PackageExtension

Experimental feature, not part of stable public API.

Returns the PackageExtension instance that depends on the package SomePackage. Will throw an error if the extension is not active (because SomePackage` hasn't been loaded).

BAT.set_rng(context::BATContext, rng::AbstractRNG)::BATContext

Experimental feature, not yet part of stable public API.

Returns a copy of context with the random number generator set to rng.

batmeasure(obj)

Experimental feature, not part of stable public API.

Convert a measure-like obj to a measure that is compatible with BAT.

struct BridgeSampling <: IntegrationAlgorithm

Experimental feature, not part of stable public API.

BridgeSampling integration algorithm.

Constructors:

• BridgeSampling(; fields...)

Fields:

• pretransform::AbstractTransformTarget: Default: PriorToNormal()

• essalg::EffSampleSizeAlgorithm: Default: EffSampleSizeFromAC()

• strict::Bool: Default: true

struct EllipsoidalNestedSampling <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Uses the julia package NestedSamplers.jl to use nested sampling algorithm.

Constructors:

• EllipsoidalNestedSampling(; fields...)

Fields:

• pretransform::AbstractTransformTarget: Default: begin pkgext(Val(:NestedSamplers)) #= /home/runner/work/BAT.jl/BAT.jl/src/extdefs/nestedsamplers_defs.jl:149 =# PriorToUniform() end

• num_live_points::Int64: Number of live-points. Default: 1000

• bound::BAT.ENSBound: Volume around the live-points. Default: ENSEllipsoidBound()

• proposal::BAT.ENSProposal: Algorithm used to choose new live-points. Default: ENSAutoProposal()

• enlarge::Float64: Scale factor for the volume. Default: 1.25

• min_ncall::Int64: Number of iterations before the first bound will be fit. Default: 2numlivepoints

• min_eff::Float64: Efficiency before fitting the first bound. Default: 0.1

• dlogz::Float64: Default: 0.01

• max_iters::Any: Default: Inf

• max_ncalls::Any: Default: 10 ^ 7

• maxlogl::Any: Default: Inf

struct GridSampler <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample from equidistantly distributed points in each dimension.

Constructors:

• GridSampler(; fields...)

Fields:

• pretransform::AbstractTransformTarget: Default: PriorToUniform()

• ppa::Int64: Default: 100

struct HierarchicalDistribution <: ContinuousDistribution

Experimental feature, not part of stable public API.

A hierarchical distribution, useful for hierarchical models/priors.

Constructors:

• HierarchicalDistribution(f::Function, primary_dist::NamedTupleDist)

with a functon f that returns a ContinuousDistribution for any variate v drawn from primary_dist.

Example:

hd = HierarchicalDistribution(
    v -> NamedTupleDist(
        baz = fill(Normal(v.bar, v.foo), 3)
    ),
    NamedTupleDist(
        foo = Exponential(3.5),
        bar = Normal(2.0, 1.0)
    )
)

varshape(hd) == NamedTupleShape(
    foo = ScalarShape{Real}(),
    bar = ScalarShape{Real}(),
    baz = ArrayShape{Real}(3)
)

v = rand(hd)

struct PriorImportanceSampler <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Importance sampler using IID samples from the prior.

Constructors:

• PriorImportanceSampler(; fields...)

Fields:

• nsamples::Int64: Default: 10 ^ 5

struct ReactiveNestedSampling <: AbstractUltraNestAlgorithmReactiv

Experimental feature, not part of stable public API.

UltraNest reactive nested sampling algorithm with.

Uses the UltraNest Python package, via UltraNest.jl (and PyCall).

Constructors:

• ReactiveNestedSampling(; fields...)

Fields:

• pretransform::AbstractTransformTarget: Default: begin pkgext(Val(:UltraNest)) #= /home/runner/work/BAT.jl/BAT.jl/src/extdefs/ultranest_defs.jl:34 =# PriorToUniform() end

• num_test_samples::Int64: Test transform and likelihood with this number of random points for errors first. Useful to catch bugs. Default: 2

• draw_multiple::Bool: If efficiency goes down, dynamically draw more points from the region between ndrawmin and ndrawmax. If set to False, few points are sampled at once. Default: true

• num_bootstraps::Int64: Number of logZ estimators and MLFriends region bootstrap rounds. Default: 30

• ndraw_min::Int64: Minimum number of points to simultaneously propose. Increase this if your likelihood makes vectorization very cheap. Default: 128

• ndraw_max::Int64: Maximum number of points to simultaneously propose. Increase this if your likelihood makes vectorization very cheap. Memory allocation may be slow for extremely high values. Default: 65536

• update_interval_volume_fraction::Float64: Update region when the volume shrunk by this amount. Default: 0.8

• log_interval::Int64: Update stdout status line every log_interval iterations. Default: -1

• show_status::Bool: Show integration progress as a status line. Default: true

• viz_callback::Union{Nothing, Function}: Callback function when region was rebuilt. Allows to show current state of the live points. Default: nothing

• dlogz::Float64: Target evidence uncertainty. This is the std between bootstrapped logz integrators. Default: 0.5

• dKL::Float64: Target posterior uncertainty. This is the Kullback-Leibler divergence in nat between bootstrapped integrators. Default: 0.5

• frac_remain::Float64: Integrate until this fraction of the integral is left in the remainder. Set to a low number (1e-2 … 1e-5) to make sure peaks are discovered. Set to a higher number (0.5) if you know the posterior is simple. Default: 0.01

• Lepsilon::Float64: Terminate when live point likelihoods are all the same, within Lepsilon tolerance. Increase this when your likelihood function is inaccurate, to avoid unnecessary search. Default: 0.001

• min_ess::Int64: Target number of effective posterior samples. Default: 400

• max_iters::Int64: maximum number of integration iterations. Default: -1

• max_ncalls::Int64: Stop after this many likelihood evaluations. Default: -1

• max_num_improvement_loops::Int64: The algorithm tries to assess iteratively where more samples are needed. This number limits the number of improvement loops. Default: -1

• min_num_live_points::Int64: Minimum number of live points throughout the run. Default: 400

• cluster_num_live_points::Int64: Require at least this many live points per detected cluster. Default: 40

• insertion_test_window::Float64: z-score used as a threshold for the insertion order test. Set to infinity to disable. Default: 10.0

• insertion_test_zscore_threshold::Float64: Number of iterations after which the insertion order test is reset. Default: 2.0

• executor::Any: Executor for posterior evaluation. Default: SequentialExec()

struct SobolSampler <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample from Sobol sequence. Also see Sobol.jl.

Constructors:

• SobolSampler(; fields...)

Fields:

• pretransform::AbstractTransformTarget: Default: PriorToUniform()

• nsamples::Int64: Default: 10 ^ 5

BAT.truncate_batmeasure(density::BATMeasure, bounds::AbstractArray{<:Interval})::BATMeasure

Experimental feature, not part of stable public API.

Truncate density to bounds, the resulting density will be effectively zero outside of those bounds. In contrast Distributions.truncated, truncate_batmeasure does not renormalize the density.

Requires varshape(density) isa ArrayShape.

Only supports densities that are essentially products of univariate distributions, as well as posterior densities with such densities as priors.

struct ValueAndThreshold{name}

Experimental feature, not part of stable public API.

Holds a (target) value, a comparison function and a threshold.

Constructor: ValueAndThreshold{name}(value, cmp_function, threshold)

Converts to a Bool accoring to cmp_function(value, threshold)

Example:

convert(Bool, ValueAndThreshold{:max_error}(3.4, <, 5.2)) == true

MCMCChainState

State of a MCMC chain.

MCMCChainStateInfo

Information about the state of an MCMC chain.

abstract type MCMCIterator end

BAT-internal, not part of stable public API.

Represents the current state of an MCMC chain.

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.getproposal(chain::SomeMCMCIter)::MCMCAlgorithm

BAT.mcmc_target(chain::SomeMCMCIter)::BATMeasure

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.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:

getproposal(chain::MCMCIterator)
mcmc_target(chain::MCMCIterator)
DensitySampleVector(chain::MCMCIterator)
mcmc_iterate!!(chain::MCMCIterator, ...)
mcmc_iterate!!(chains::AbstractVector{<:MCMCIterator}, ...)
isvalidchain(chain::MCMCIterator)
isviablechain(chain::MCMCIterator)

abstract type MCMCProposal

Abstract type for MCMC proposal algorithms.

abstract type MCMCProposalState

Abstract type for MCMC proposal algorithm states.

abstract type MCMCProposalTunerState

Abstract type for MCMC tuning algorithm states.

MCMCState

Carrier type for the states of an MCMC chain, and the states of the tuning and tempering algorithms used for sampling.

abstract type MCMCTempering

Abstract type for MCMC tempering algorithms.

abstract type MCMCTransformTunerState

Abstract type for MCMC tuning algorithm states.

BAT.PolarShellDistribution{T<:Real} <: Distributions.Distribution{Multivariate,Continuous}

Experimental feature, not yet part of stable public API.

A doughnut-like distribution in two dimensions, in [r, phi] polar coordinates.

The distribution results from transforming the radial component of a base distribution the transport from a standard normal to a given radial distribution.

Constructor:

    PolarShellDistribution(
        base_dist = MvNormal(Diagonal([1,1])),
        radial_dist = LogNormal(0, 1)
    )

abstract type TemperingState

Abstract type for MCMC tempering algorithm states.