abstract type BAT.AbstractAffineTransform <: BAT.AbstractAdaptiveTransform

BAT-internal, not part of stable public API.

Supertype for adaptive affine space transformations x = A * z + b, which differ in the structure they impose on A.

Implementation

Subtypes must have a field init holding a BAT.AbstractTransformInit algorithm, and must specialize BAT._affine_init_A to build A in their structure from an approximate covariance. Transform tunings maintain that structure across updates and specialize on the concrete type in turn (see BAT._fisher_estimator for FisherTransformTuning).

abstract type AbstractSampleGenerator

BAT-internal, not part of stable public API.

Abstract super type for sample generators.

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.

abstract type BATMeasure <:AbstractMeasure

BAT-internal, not part of stable public API.

Subtypes must implement DensityInterface.logdensityof and ValueShapes.varshape.

BATPushFwdMeasure

BAT-internal, not part of stable public API.

BATPwrMeasure

BAT-internal, not part of stable public API.

struct BATSuperpositionMeasure <: BATMeasure

BAT-internal, not part of stable public API.

Superposition (sum) of measures.

Extended help

The log-density of the superposition is computed directly via logaddexp over the component log-densities in an autodiff-friendly way.

Superposing equal BAT measures does not collapse them, for type stability.

MeasureBase.superpose generates a BATSuperpositionMeasure if its first argument is a BATMeasure, all other arguments must then be a BATMeasure as well.

struct BATWeightedMeasure <: BATMeasure

BAT-internal, not part of stable public API.

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

struct CholeskyWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

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

See A. Kessy, A. Lewin and K. Strimmer, "Optimal Whitening and Decorrelation" (2018).

Constructors:

• CholeskyWhitening()

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

abstract type ENSBound

Experimental feature, not part of stable public API.

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

struct BAT.ENSEllipsoidBound <: ENSBound

Experimental feature, not part of stable public API.

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

See P. Mukherjee, D. Parkinson and A. R. Liddle, "A Nested Sampling Algorithm for Cosmological Model Selection" (2006).

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.

See F. Feroz, M. P. Hobson and M. Bridges, "MultiNest: an efficient and robust Bayesian inference tool for cosmology and particle physics" (2009).

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.

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.

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

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.

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

Constructors:

• ENSSlice(; fields...)

Fields:

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

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

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.

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

struct BAT.JointLikelihood <: MeasureBase.AbstractLikelihood

BAT-internal, not part of stable public API.

Combines several likelihoods that share a common parameter space.

User code should not instantiate JointLikelihood directly, but use joint_likelihood instead.

struct BAT.LFDensity{F}

BAT-internal, not part of stable public API.

Wraps a log-density function log_f.

abstract type BAT.AbstractTransformInit

BAT-internal, not part of stable public API.

Abstract type for algorithms that initialize adaptive MCMC space transformations.

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.

struct LogDVal{T<:Real}

BAT-internal, not part of stable public API.

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

BAT.MCMCSampleGenerator

BAT-internal, not part of stable public API.

MCMC sample generator, holds the (mutable) states of the MCMC chains. Consumers must not mutate the chain states, continuing sample generation requires a deep copy.

Constructors:

MCMCSampleGenerator(mc_state::AbstractVector{<:MCMCIterator})

struct BAT.MCMCStepInfo

BAT-internal, not part of stable public API.

Per-walker information about one MCMC transition, produced by mcmc_propose!! and consumed by the tuning machinery and sample weighting. p_accept is always present; gradient-based proposals additionally provide the z-space log-density gradients at the selected states (z_grads) and trajectory diagnostics (divergent, tree_depth, n_leapfrog), which are nothing for proposals that don't compute them. walker_order indexes these vectors in logical-walker order.

BAT.MeasureLike = Union{...}

BAT-internal, not part of stable public API.

Union of all types that BAT will accept as a measures or convert to measures.

struct NoWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

No-op whitening transformation, leaves samples unchanged.

Constructors:

• NoWhitening()

OnlineMvCov{T<:AbstractFloat,W} <: AbstractMatrix{T}

BAT-internal, not part of stable public API.

Implementation based on the variance calculation algorithms of B. P. Welford (1962) and D. H. D. West (1979).

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

OnlineMvMean{T<:AbstractFloat} <: AbstractVector{T}

BAT-internal, not part of stable public API.

Multivariate mean implemented via Kahan-Babuška-Neumaier summation (A. Neumaier (1974)).

OnlineUvMean{T<:AbstractFloat}

BAT-internal, not part of stable public API.

Univariate mean implemented via Kahan-Babuška-Neumaier summation (A. Neumaier (1974)).

OnlineUvVar{T<:AbstractFloat,W}

BAT-internal, not part of stable public API.

Implementation based on the variance calculation algorithms of B. P. Welford (1962) and D. H. D. West (1979).

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

struct BAT.PriorApproxTransformInit <: BAT.AbstractTransformInit

BAT-internal, not part of stable public API.

Initializes affine space transformations from the approximate covariance and mean of the prior.

struct SampleTransformation <: TransformAlgorithm

BAT-internal, not part of stable public API.

struct StanLikeTuning <: MCMCTransformTuning

BAT-internal, not part of stable public API.

Tunes MCMC space transformations from sample covariance estimates, accumulated over Stan-like adaptation windows of doubling size (see the Stan HMC parameters documentation).

Constructors:

• StanLikeTuning(; fields...)

Fields:

• init_buffer::Int64: width of initial fast adaptation interval Default: 75

• term_buffer::Int64: width of final fast adaptation interval Default: 50

• window_size::Int64: initial width of slow adaptation interval Default: 25

StandardMvNormal{T<:Real} <: Distributions.AbstractMvNormal

BAT-internal, not part of stable public API.

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)

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

BAT-internal, not part of stable public API.

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

Constructor:

    StandardMvUniform(n::Integer)
    StandardMvUniform{T<:Real}(n::Integer)

StandardUvNormal{T<:Real} <: Distributions.Distribution{Univariate,Continuous}

BAT-internal, not part of stable public API.

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

Constructor:

    StandardUvNormal()
    StandardUvNormal{T<:Real}()

StandardUvUniform{T<:Real} <: Distributions.Distribution{Univariate,Continuous}

BAT-internal, not part of stable public API.

A standard uniform distribution between zero and one.

Constructor:

    StandardUvUniform()
    StandardUvUniform{T<:Real}()

struct StatisticalWhitening <: WhiteningAlgorithm

BAT-internal, not part of stable public API.

Whitening transformation based statistical whitening.

See A. Kessy, A. Lewin and K. Strimmer, "Optimal Whitening and Decorrelation" (2018).

Constructors:

• StatisticalWhitening()

struct StepSizeAdaptor <: BAT.HMCTuning

BAT-internal, not part of stable public API.

Tunes the scalar proposal scale of gradient-based MCMC proposals via Nesterov dual averaging, targeting the proposal's target acceptance rate: the leapfrog step size of HamiltonianMC and the Langevin step scale of MALAProposal.

See M. D. Hoffman and A. Gelman, "The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo" (2014), section 3.2.

Invalid adaptation controls are rejected with ArgumentError when the proposal tuner state is constructed, before sampling begins. An update or finalization that cannot represent a finite positive scale raises ArgumentError without installing an invalid scale.

Constructors:

• StepSizeAdaptor(; fields...)

Fields:

• gamma::Real: Positive finite adaptation regularization scale. Default: 0.05

• t0::Real: Finite non-negative adaptation iteration offset. Default: 10.0

• kappa::Real: Finite adaptation relaxation exponent in (0.5, 1]. Default: 0.75

struct BAT.DiagonalAffineTransform <: BAT.AbstractAffineTransform

BAT-internal, not part of stable public API.

Adaptive affine space transformation x = A * z + b with a diagonal matrix A, initialized via an BAT.AbstractTransformInit algorithm. Cheap to apply and to tune, but blind to correlations.

Constructors:

• DiagonalAffineTransform(; fields...)

Fields:

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

struct BAT.TriangularAffineTransform <: BAT.AbstractAffineTransform

BAT-internal, not part of stable public API.

Adaptive affine space transformation x = A * z + b with a lower-triangular matrix A, initialized via an BAT.AbstractTransformInit algorithm.

Constructors:

• TriangularAffineTransform(; fields...)

Fields:

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

struct BAT.UnitTransformInit <: BAT.AbstractTransformInit

BAT-internal, not part of stable public API.

Initializes affine space transformations to the identity map. The natural initialization for inner components of an AdaptiveTransformChain, where the outer components already carry the target geometry.

struct UnshapeTransformation <: TransformAlgorithm

BAT-internal, not part of stable public API.

abstract type WhiteningAlgorithm

BAT-internal, not part of stable public API.

Abstract type for sample whitening algorithms.

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.

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.

See S. P. Brooks and A. Gelman, "General Methods for Monitoring Convergence of Iterative Simulations" (1998); the corrected option implements the paper's df-corrected variant.

checked_logdensityof(measure::AbstractMeasure, v::Any, T::Type{<:Real})

BAT-internal, not part of stable public API.

Evaluates the measure's log-density value via DensityInterface.logdensityof and performs additional checks.

Throws a BAT.EvalException on any of these conditions:

• The variate shape of measure (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.

BAT.dist_samples_mean_zscores(
    dist::Distribution, smpls::DensitySampleVector,
    context::BATContext = get_batcontext()
)

BAT-internal, not part of stable public API.

Z-scores of the sample means of smpls against the true means of dist, based on Monte Carlo standard errors derived from the effective sample size.

Requires mean and var to be defined for unshaped(dist).

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.

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.

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.

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.

get_bin_centers(marg::MarginalDist)

BAT-internal, not part of stable public API.

Returns a vector of the bin-centers.

get_iid_sampleable_approx(target)

BAT-internal, not part of stable public API.

Obtain a measure from the target that can be sampled to obtain iid samples for a MCMCGlobalProposal.

getlikelihood(posterior::AbstractPosteriorMeasure)::BATDensity

BAT-internal, not part of stable public API.

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

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.

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.

See A. Gelman and D. B. Rubin, "Inference from Iterative Simulation Using Multiple Sequences" (1992).

has_uhc_support(m)::Bool

BAT-internal, not part of stable public API.

Is the support of measure m limited to the unit hypercube?

hmc_find_good_stepsize(
    rng::AbstractRNG, f_logdgrad::Function, q0::AbstractVector{<:Real};
    init_stepsize::Real = 0.1, max_niters::Integer = 100
)

BAT-internal, not part of stable public API.

Heuristically search a leapfrog step size at position q0 for which the single-step Metropolis acceptance ratio lies between 1/4 and 3/4 (see M. D. Hoffman and A. Gelman, "The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo" (2014), algorithm 4).

Given a vector of positions instead of a single position, probes every position and returns the smallest step size found.

hmc_nuts_transition(
    rng::AbstractRNG, f_logdgrad::Function, z0::HMCPhasePoint,
    stepsize::Real, max_depth::Integer, max_delta_energy::Real
)

BAT-internal, not part of stable public API.

Perform a single multinomial NUTS transition from phase point z0, doubling the trajectory until the generalized no-U-turn condition triggers, the energy error exceeds max_delta_energy or the tree depth reaches max_depth.

f_logdgrad(q) must return the tuple (logd, grad) of the target log-density and its gradient.

Returns a NamedTuple with the fields z (the sampled phase point), p_accept (average leapfrog Metropolis acceptance probability), depth, n_leapfrog and divergent.

BAT.is_log_zero(x::Real, T::Type = 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.

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.

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

BAT-internal, not part of stable public API.

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.

logvalof(r::NamedTuple{(...,:log,...)})::Real
logvalof(r::LogDVal)::Real

BAT-internal, not part of stable public API.

maximize_density(f_logdensity, x_init::AbstractVector{<:Real}, algorithm, context::BATContext)

BAT-internal, not part of stable public API.

Maximize the log-density function f_logdensity, starting at x_init, using optimization algorithm.

The user is responsible for shaping flogdensity in a way that works well with the algorithm (typically by transforming it to an unbounded space), `maximizedensity` does not apply automatic space transformations.

Returns a NamedTuple (result = x_optimal, trace = ..., info = ...) with the optimum in the same space, an optional optimization trace and algorithm-specific optimizer information.

trace is nothing unless trace recording was requested via the algorithm (field store_trace of OptimAlg and OptimizationAlg). When present, it is a NamedTuple of iteration-indexed vectors: v (the iterates) and, depending on backend and optimizer, logd (the log-density values at the iterates) and grad_logd (the log-density gradients at the iterates).

struct BispacedMeasure <: BATMeasure

BAT-internal, not part of stable public API.

A measure in its primary space, together with an optional representation of it in a transformed space.

Constructors:

BispacedMeasure(main::BATMeasure)  # no transformed representation
BispacedMeasure(f_transform, main)  # transformed side generated via f_transform
BispacedMeasure(main::BATMeasure, transformed::Union{BATMeasure,Nothing}, f_hash::UInt)

As a measure, a BispacedMeasure behaves like its main side. The pair itself does not identify the transformed space, that meaning comes from the transform_intent of the EvaluatedMeasure the pair is part of.

Implementation

f_hash is the hash of the transformation function that produced the transformed side. It acts as a cheap compatibility witness when pairs are adopted into or consumed from an EvaluatedMeasure: a non-matching hash results in an error, never in silently wrong content. UInt(0) means that no claim is made, either because there is no transformed side or because the claim was invalidated. The witness only covers the connection between the two sides, supplying a fitting main side is the responsibility of the supplier.

hash may be specialized for transformation function types to make the witness value-based instead of object-based. Without such a specialization the fallback is objectid, so stamps do not survive serialization or a new session. This errs on the safe side, since on a mismatch the transformed content can simply be re-derived. The witness is a strong practical guard, not a proof of identity: a hash collision could in principle let incompatible content pass.

BAT.pathfinder_gaussian_fit(
    f_logd::Function, x0::AbstractVector{<:Real},
    optalg, context::BATContext;
    history_length::Integer = 6, ndraws_elbo::Integer = 5
)

BAT-internal, not part of stable public API.

Runs single-path Pathfinder (Zhang et al. (2022)) from x0 and returns the mean μ, dense covariance Σ and elbo of the maximum-ELBO local Gaussian approximation of the target along an L-BFGS trajectory, as a NamedTuple, or nothing if no approximation with a finite ELBO is found.

The trajectory is generated by maximizing the log-density function f_logd via maximize_density with optalg, which must be a gradient-based backend that records iterates and gradients (e.g. an OptimAlg with Optim.LBFGS). Optimizer failures count as path-local failures.

repetition_to_weights(v::AbstractVector)

BAT-internal, not part of stable public API.

Drop (subsequently) repeated samples by adding weights.

smallest_credible_intervals(X, W = UnitWeights(...); p = nothing,
    nsigma_equivalent = nothing, mode = :disjoint)

BAT-internal, not part of stable public API.

Return empirical credible intervals. Use :connected for the shortest single interval. Set p in (0, 1] or nsigma_equivalent; the default is one sigma. Log-weight rounding may conservatively widen intervals.

smallest_credible_intervals(smpl::DensitySampleVector{<:AbstractVector{<:Real}}; kwargs...)

BAT-internal, not part of stable public API.

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

@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)[:].

supports_rand(m)

BAT-internal, not part of stable public API.

Check whether a measure-like object m supports rand.

BAT.transform_function(intent::TransformIntent, object)

BAT-internal, not part of stable public API.

Return the transformation function that intent implies for object.

A TransformIntent, together with an object to be transformed, implies a concrete transformation function; the same intent and object always yield the same transformation. Methods of transform_function must derive the transformation from the intent and the object alone.

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_batmeasure, in conjunction with BAT.truncate_dist_hard.

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, logweight = logweight)

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

Mainly used to implement BAT.truncate_batmeasure.