Experimental features

These are experimental features. Forward/backward compatibility does not follow Julia's semantic versioning rules. Instead, compatibility is only guaranteed across changes in patch version, but not across changes of minor (or major) version.

The features listed here are likely to transition to the stable API in future versions, but may still evolve in a API-breaking fashion during that process.

BAT.ARPWeightingType
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()
source
BAT.bat_compareFunction
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, ...)
source
BAT.bat_integrated_autocorr_lenFunction
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.

Note

Do not add add methods to bat_integrated_autocorr_len, add methods to bat_integrated_autocorr_len_impl instead.

source
BAT.bat_marginalmodeFunction
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, ...)
Note

Do not add add methods to bat_marginalmode, add methods to bat_marginalmode_impl instead.

source
BAT.auto_renormalizeFunction
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.

source
BAT.batsampleableFunction
batsampleable(obj)

Experimental feature, not part of stable public API.

Convert obj into something that BAT can sample from.

source
BAT.BinnedModeEstimatorType
struct BinnedMarginalModes <: AbstractModeEstimator

Experimental feature, not part of stable public API.

Bin data to estimate modes.

Constructor: BinnedModeEstimator(; fields...)

Fields:

  • binning::Any: Default: FreedmanDiaconisBinning()
source
BAT.DistributionTransformType
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)
source
BAT.enable_error_logFunction
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.

source
BAT.error_logFunction
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.

source
BAT.EvalExceptionType
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).

source
BAT.ext_defaultFunction
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.

source
BAT.get_adselectorFunction
BAT.get_adselector(context::BATContext)

Experimental feature, not yet part of stable public API.

Returns the automatic differentiation selector specified in context.

source
BAT.PackageExtensionType
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.

source
BAT.pkgextFunction
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).

source
BAT.set_rngFunction
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.

source
BAT.batmeasureFunction
batmeasure(obj)

Experimental feature, not part of stable public API.

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

source
BAT.BridgeSamplingType
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

source
BAT.EllipsoidalNestedSamplingType
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

Note

This functionality is only available when the NestedSamplers.jl package is loaded (e.g. via import).

source
BAT.GridSamplerType
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

source
BAT.HierarchicalDistributionType
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)
Note

All fields of HierarchicalDistribution are considered internal and subject to change without deprecation.

source
BAT.PriorImportanceSamplerType
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
source
BAT.ReactiveNestedSamplingType
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()

Note

This functionality is only available when the UltraNest package is loaded (e.g. via import UltraNest).

source
BAT.SobolSamplerType
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

source
BAT.truncate_batmeasureFunction
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.

source
BAT.ValueAndThresholdType
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
source