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. MetropolisHastings). 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::AnyMeasureOrDensity)

Experimental feature, not part of stable public API.

Returns (result = new_measure, logrenormf = logrenormf).

Tries to automatically renormalize measure if a maxium 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()

abstract type DistributionTransform{VT<:AbstractValueShape,VF<:AbstractValueShape} <: 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, density::AbstractMeasureOrDensity, v::Any, ret::Any)

Fields:

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

• density::BAT.AbstractMeasureOrDensity: Density being evaluated.

• v::Any: Variate at which the evaluation of density (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.

struct BAT.LogUniform{T<:Real} <: Distributions.Distribution{Univariate,Continuous}

Experimental feature, not part of stable public API.

The log-uniform distribution (reciprocal distribution) over an interval $[a, b]$.

Constructors:

• LogUniform(a::Real, b::Real)

See also Reciprocal distribution on Wikipedia.

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.

struct BridgeSampling <: IntegrationAlgorithm

Experimental feature, not part of stable public API.

BridgeSampling integration algorithm.

Constructors:

• BridgeSampling(; fields...)

Fields:

• trafo::AbstractTransformTarget: Default: PriorToGaussian()

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

• trafo::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:

• trafo::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:

• trafo::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: default_executor()

BAT.renormalize_density(density::AbstractMeasureOrDensity, logrenormf::Real)::AbstractMeasureOrDensity

Experimental feature, not part of stable public API.

Renormalies density with the logarithmic renormalization factor, so that

logdensityof(renormalize_density(density, logrenormf))(v) ==
    logdensityof(density)(v) + logrenormf

struct SobolSampler <: AbstractSamplingAlgorithm

Experimental feature, not part of stable public API.

Sample from Sobol sequence. Also see Sobol.jl.

Constructors:

• SobolSampler(; fields...)

Fields:

• trafo::AbstractTransformTarget: Default: PriorToUniform()

• nsamples::Int64: Default: 10 ^ 5

BAT.truncate_density(density::AbstractMeasureOrDensity, bounds::AbstractArray{<:Interval})::AbstractMeasureOrDensity

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_density 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