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()

batalgorithm(algorithm)

Experimental feature, not part of stable public API.

Map algorithm to its BAT equivalent.

Wraps backend configurations and third-party algorithms in the BAT algorithm that uses them. Acts as the identity on BAT algorithms.

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

Experimental feature, not part of stable public API.

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

See N. Smirnov, "Table for Estimating the Goodness of Fit of Empirical Distributions" (1948).

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 part of stable public API.

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]
)

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 = v, ...)

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 maximum log-density value is available, returns measure unchanged otherwise.

struct BinnedMarginalModes <: AbstractModeEstimator

Experimental feature, not part of stable public API.

Bin data to estimate modes.

Constructor: BinnedModeEstimator(; fields...)

Fields:

• binning::Any: Default: FreedmanDiaconisBinning()

convert_for(function, obj)

Experimental feature, not part of stable public API.

Convert obj into something that function can use.

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)

struct BAT.LowRankAffineTransform <: BAT.AbstractAffineTransform

Experimental feature, not part of stable public API.

Adaptive affine space transformation x = A * z + b with A a diagonal-plus-low-rank Gram factor (A * A' == D + W * S * W', represented as a MatrixShapedOperators Woodbury operator factor): a diagonal base geometry plus a correction along the directions where a diagonal geometry is insufficient. Tuning selects those directions by an eigenvalue cutoff (see FisherTransformTuning), which regularizes the geometry estimate compared to a full triangular matrix.

Applying the transformation costs O(rank * n_dims). Dynamic fitting uses a thin basis. Initialization may use a dense decomposition governed by max_rank.

Dynamic Fisher tuning can make at most one rank-one correction attempt when cutoff >= 1.5, the dimension is at most 32, and a tuning cycle has enough steps; otherwise it tunes only the diagonal base. It fits from a fixed window and uses a guard followed by held-out validation. HMC keeps the diagonal kernel during both. MALA installs the candidate provisionally during its guard so it can retune and mix, then keeps it after acceptance or restores the diagonal transform after rejection. The correction must beat both the frozen diagonal base and its own diagonal projection. Each paired Fisher-loss comparison needs a positive one-sided 99% normal lower bound with at least 20 effective observations. This rejects purely diagonal updates without restricting the shape of a correlation direction.

This is a conservative held-out heuristic, not a finite-sample error-rate guarantee. Its asymptotic interpretation assumes stationary, mixing validation chains, finite long-run paired-loss variance, and independent walkers. Heavy-tailed cases outside those assumptions have only empirical evidence.

Constructors:

• LowRankAffineTransform(; fields...)

Fields:

• init::BAT.AbstractTransformInit: Transform initialization algorithm. Default: PriorApproxTransformInit()

• max_rank::Int64: Maximum rank of the non-diagonal correction during initialization. 0 means no explicit cap. Dynamic Fisher tuning currently attempts one rank-one correction. Default: 0

• cutoff::Float64: Relative eigenvalue cutoff used during initialization. Dynamic Fisher tuning requires cutoff >= 1.5 and uses its fixed validated rank-one policy. Default: 1.5

struct BAT.PathfinderTransformInit <: BAT.AbstractTransformInit

Experimental feature, not part of stable public API.

Initializes affine space transformations from local Gaussian target approximations obtained by running the Pathfinder algorithm (see BAT.pathfinder_gaussian_fit) from each initial walker position.

Requires the BATContext to include an ADSelector and a gradient-based optimization backend: by default the Optim package must be loaded, alternatively set optalg explicitly.

See L. Zhang, B. Carpenter, A. Gelman and A. Vehtari, "Pathfinder: Parallel quasi-Newton variational inference", JMLR 23(306) (2022).

Constructors:

• PathfinderTransformInit(; fields...)

Fields:

• optalg::Any: Density maximization backend that generates the L-BFGS trajectory, must record iterates and gradients (see maximize_density). Default: defaultpathfinder_optalg()

• history_length::Int64: L-BFGS history length of the inverse-Hessian estimates. Default: 6

• ndraws_elbo::Int64: Number of Monte Carlo draws used to estimate the ELBO. Default: 5

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

Experimental feature, not part of stable public API.

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.evalmeasure_impl(
    em::EvaluatedMeasure,
    algorithm,
    context::BATContext
)::EvaluatedMeasure

Experimental feature, not part of stable public API.

Used internally by evalmeasure. Specialize BAT.evalmeasure_impl to implement new measure/distribution evaluation algorithms.

Implementations receive the evaluation target as an EvaluatedMeasure and return an updated evaluated measure for the same underlying measure, so unevaluated(result) === unevaluated(em). The result is constructed via EvaluatedMeasure(em; ...); implementations decide themselves which entries of em to overwrite and which to only fill if absent, and they must record their evaluation by setting evalinfo = MeasureEvalInfo(algorithm, ...). Implementations that produce transformed-space content pass their transform_intent and f_transform in the same update, and report sample pairs stamped with the hash of that transformation (see BAT.BispacedMeasure).

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 part of stable public API.

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 part of stable public API.

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 part of stable public API.

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.

See X.-L. Meng and W. H. Wong, "Simulating ratios of normalizing constants via a simple identity: a theoretical exploration" (1996).

Constructors:

• BridgeSampling(; fields...)

Fields:

• pretransform::TransformIntent: Default: NormalBased()

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

See J. Skilling, "Nested sampling for general Bayesian computation" (2006).

Constructors:

• EllipsoidalNestedSampling(; fields...)

Fields:

• pretransform::TransformIntent: Default: begin pkgext(Val(:NestedSamplers)) #= /home/runner/work/BAT.jl/BAT.jl/src/extdefs/nestedsamplers_defs.jl:163 =# UniformBased() 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 EllipticalSliceMCMCSampling <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample a posterior with EllipticalSliceSampling.jl using a direct Gaussian prior transform. The sampler draws a Gaussian vector to define an ellipse through the current state. Each update draws a threshold uniformly below the current likelihood. It draws angle proposals uniformly from a bracket spanning the ellipse. It shrinks the bracket after rejections until a proposal's likelihood exceeds the threshold.

See I. Murray, R. Adams and D. MacKay, "Elliptical slice sampling" (2010).

This functionality requires EllipticalSliceSampling.jl to be loaded.

Constructors:

• EllipticalSliceMCMCSampling(; fields...)

Fields:

• init::InitvalAlgorithm: Initial-value algorithm. Default: begin pkgext(Val(:EllipticalSliceSampling)) #= /home/runner/work/BAT.jl/BAT.jl/src/extdefs/ellipticalslicesampling_defs.jl:30 =# InitFromTarget() end

• nsamples::Int64: Number of retained samples. Default: 10 ^ 4

• n_burnin::Int64: Number of initial samples to discard. Default: 10 ^ 3

struct GridSampler <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample from equidistantly distributed points in each dimension.

Constructors:

• GridSampler(; fields...)

Fields:

• pretransform::TransformIntent: Default: UniformBased()

• 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 PythonCall).

See J. Buchner, "UltraNest - a robust, general purpose Bayesian inference engine" (2021).

Constructors:

• ReactiveNestedSampling(; fields...)

Fields:

• pretransform::TransformIntent: Default: begin pkgext(Val(:UltraNest)) #= /home/runner/work/BAT.jl/BAT.jl/src/extdefs/ultranest_defs.jl:37 =# UniformBased() 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 (see J. Buchner, "A statistical test for Nested Sampling algorithms" (2016)). 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 SliceMCMCSampling <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample a transformed target with SliceSampling.jl. The default sampler visits coordinates in random order. Each update draws a threshold uniformly below the current density. It expands a coordinate interval and draws proposals uniformly within it. It shrinks the interval after rejections until a proposal's density exceeds the threshold.

See R. M. Neal, "Slice sampling" (2003).

This functionality requires SliceSampling.jl to be loaded.

Constructors:

• SliceMCMCSampling(; fields...)

Fields:

• pretransform::TransformIntent: Transform the target into an unconstrained vector space. Default: begin pkgext(Val(:SliceSampling)) #= /home/runner/work/BAT.jl/BAT.jl/src/extdefs/slicesampling_defs.jl:30 =# NormalBased() end

• init::InitvalAlgorithm: Initial-value algorithm. Default: InitFromTarget()

• sampler::Any: SliceSampling.jl sampler. Default: ext_default(pkgext(Val(:SliceSampling)), Val(:SAMPLER))

• nsamples::Int64: Number of retained samples. Default: 10 ^ 4

• n_burnin::Int64: Number of initial samples to discard. Default: 10 ^ 3

struct SobolSampler <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample from Sobol sequence. Also see Sobol.jl.

See I. M. Sobol', "On the distribution of points in a cube and the approximate evaluation of integrals" (1967).

Constructors:

• SobolSampler(; fields...)

Fields:

• pretransform::TransformIntent: Default: UniformBased()

• 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

BAT.validate_evalmeasure(
    em::EvaluatedMeasure;
    context::BATContext = get_batcontext()
)::EvaluatedMeasure

Experimental feature, not part of stable public API.

Verify the transformed-space-view contract of em by re-deriving the view from (em.transform_intent, unevaluated(em)) and comparing values, and spot-check the stored sample log-densities against the measure (and its transformed representation). NaN sample log-densities are admissible (they mark values lost in LADJ-less sample transport), and log-density checks are skipped where the measure in question can't be point-evaluated. Computationally expensive, intended for tests and debugging, not for performance-critical code. Throws an exception if em violates its contract (or if transformed-space content exists but no validation points can be derived to verify it), returns em otherwise.

MCMCChainState

Experimental feature, not part of stable public API.

State of a MCMC chain.

MCMCChainStateInfo

Experimental feature, not part of stable public API.

Information about the state of an MCMC chain.

abstract type MCMCIterator end

Experimental feature, 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

Experimental feature, not part of stable public API.

Abstract type for MCMC proposal algorithms.

abstract type MCMCProposalState

Experimental feature, not part of stable public API.

Abstract type for MCMC proposal algorithm states.

abstract type MCMCProposalTunerState

Experimental feature, not part of stable public API.

Abstract type for MCMC tuning algorithm states.

MCMCState

Experimental feature, not part of stable public API.

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

abstract type MCMCTempering

Experimental feature, not part of stable public API.

Abstract type for MCMC tempering algorithms.

abstract type MCMCTransformTunerState

Experimental feature, not part of stable public API.

Abstract type for MCMC tuning algorithm states.

struct BAT.MeasureEvalInfo

Experimental feature, not part of stable public API.

Properties:

• algorithm: The algorithm used to evaluate the measure.
• result: Algorithm-specific evaluation result.

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

Experimental feature, not part of stable public API.

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 SimpleMCMCProposalState

Experimental feature, not part of stable public API.

Abstract type for the states of simple MCMC proposal algorithms, that are implemented in BAT.jl. This is used to treat more complicated algorithms -that may depend on external packages- differently.

abstract type TemperingState

Experimental feature, not part of stable public API.

Abstract type for MCMC tempering algorithm states.