Edit on GitHub

API

Modules

Types and constants

Functions and macros

Documentation

BATBase.AbstractDensity — Type
abstract type AbstractDensity

Subtypes of AbstractDensity (e.g. MyDensity) must implement the methods

  • BATBase.eval_logval_unchecked(density::MyDensity)

To query the logarithm of the density for a given point/variate v, use the function logdensityof.

For likelihood densities, implementing `BATBase.evallogvalunchecked is typically sufficient, since shape, and variate bounds can be inferred from the prior.

Densities with a known variate shape may also implement

  • ValueShapes.varshape(density::MyDensity)

Densities with known variate bounds may also implement

  • BAT.var_bounds(density::MyDensity)
Note

Only implement BAT.var_bounds in special cases. BAT.var_bounds is not part of the stable public BATBase.jl and BAT.jl APIs and subject to change without deprecation.

source
BATBase.AbstractDensitySample — Type
abstract type AbstractDensitySample

Abstract type for samples drawn from an AbstractDensity.

Subtypes (e.g. MyDensitySample) must support:

  • Base.getproperty(s::MyDensitySample, :v)::Any: Variate value.

  • Base.getproperty(s::MyDensitySample, :logd)::Real: Result of logdensityof(some_density)(v)

  • Base.getproperty(s::MyDensitySample, :weight)::Real: Weight of the sample.

  • Base.getproperty(s::MyDensitySample, :info)::Any: Additional info on the provenance of the sample. Content depends on the sampling algorithm.

  • Base.getproperty(s::MyDensitySample, :aux)::Any: Custom user-defined information attached to the sample.

source
BATBase.AbstractDensitySampleVector — Type
abstract type AbstractDensitySampleVector <: AbstractVector{<:AbstractDensitySample}

Abstract type for multiple samples drawn from an AbstractDensity.

Subtypes must support the Tables.jl API with access both as a vector of structs and a struct of vectors, and

  • Base.getproperty(s::MyDensitySample, :v)::AbstractVector{<:Any}
  • Base.getproperty(s::MyDensitySample, :logd)::AbstractVector{<:Real}
  • Base.getproperty(s::MyDensitySample, :weight)::AbstractVector{<:Real}
  • Base.getproperty(s::MyDensitySample, :info)::AbstractVector{<:Any}
  • Base.getproperty(s::MyDensitySample, :aux)::AbstractVector{<:Any}

See AbstractDensitySample for the semantics of the columns.

source
BATBase.AbstractDistributionDensity — Type
abstract type AbstractDistributionDensity <: DistLikeDensity

A density that can be converted efficiently to a Distributions.Distribution.

Subtypes (e.g. MyDistributionDensity) support, in addition to the DistLikeDensity interface, support:

  • Base.convert(Distributions.Distribution, density::MyDistributionDensity)

A d::ContinuousDistribution can be converted into (resp. wrapped in) an suitable subtype of DistLikeDensity via conv(AbstractDistributionDensity, d).

Note

This functionality is implemented in BAT.jl, not in BATBase.jl.

source
BATBase.AbstractTransformToInfinite — Type
abstract type AbstractTransformToInfinite <: AbstractDensityTransformTarget

Abstract type for density transformation targets that specify are transformation into unbounded space.

The density that results from such a transformation must be unbounded in all dimensions and that should taper off to zero somewhat smoothly in any direction.

source
BATBase.AbstractTransformToUnitspace — Type
abstract type AbstractTransformToUnitspace <: AbstractDensityTransformTarget

Abstract type for density transformation targets that specify a transformation into the unit hypercube.

source
BATBase.DensityIdentityTransform — Type
struct DensityIdentityTransform <: TransformAlgorithm

A no-op density transform algorithm that leaves any density unchanged.

Constructors:

  • DensityIdentityTransform()
source
BATBase.DifferentiationAlgorithm — Type
abstract type DifferentiationAlgorithm

Experimental feature, not part of stable public API.

Abstract type for integrated autocorrelation length estimation algorithms.

source
BATBase.DistLikeDensity — Type
abstract type DistLikeDensity <: AbstractDensity

A density that implements part of the Distributions.Distribution interface. Such densities are suitable for use as a priors.

In contrast to a distribution, the integral of a DistLikeDensity is not required to be normalized to one (but will be, in many cases).

Typically, custom priors should be implemented as subtypes of Distributions.Distribution. BAT will automatically wrap them in a subtype of AbstractDistributionDensity, which is a subtype of DistLikeDensity.

Subtypes of DistLikeDensity are required to support more functionality than an AbstractDensity, but less than a Distribution{Multivariate,Continuous}.

A d::ContinuousDistribution can be converted into (wrapped in) an suitable subtype of AbstractDistributionDensity via conv(DistLikeDensity, d).

The following functions must be implemented for subtypes (e.g. MyDistLikeDensity), in addition to the mandatory AbstractDensity interface:

  • ValueShapes.varshape(density::MyDistLikeDensity)

  • Distributions.sampler(density::MyDistLikeDensity)

Note

The function BAT.var_bounds is not part of the stable public BATBase.jl and BAT.jl APIs and subject to change without deprecation.

source
BATBase.FullDensityTransform — Type
struct FullDensityTransform <: TransformAlgorithm

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:

  • FullDensityTransform()
source
BATBase.InitvalAlgorithm — Type
abstract type BAT.InitvalAlgorithm

Abstract type for BAT initial/starting value generation algorithms.

Many algorithms in BAT, like MCMC and optimization, need initial/starting values.

source
BATBase.NoDensityTransform — Type
struct NoDensityTransform <: AbstractDensityTransformTarget

The identity density transformation target, specifies that densities should not be transformed.

Constructors:

  • NoDensityTransform()
source
BATBase.PriorSubstitution — Type
struct PriorSubstitution <: TransformAlgorithm

Substitute the prior by a given distribution and transform the likelihood accordingly. The log(abs(jacobian)) of the transformation does not need to be auto-differentiable even for operations that use the gradient of the posterior.

Constructors:

  • PriorSubstitution()
source
BATBase.PriorToGaussian — Type
struct PriorToGaussian <: AbstractTransformToInfinite

Specifies that posterior densities should be transformed in a way that makes their pior equivalent to a standard multivariate normal distribution with an identity covariance matrix.

Constructors:

  • PriorToGaussian()
source
BATBase.PriorToUniform — Type
struct PriorToUniform <: AbstractTransformToUnitspace

Specifies that posterior densities should be transformed in a way that makes their pior equivalent to a uniform distribution over the unit hypercube.

Constructors:

  • PriorToUniform()
source
BATBase.AnyDensityLike — Type
BAT.AnyDensityLike = Union{...}

Union of all types that BAT will accept as a probability density, resp. that convert(AbstractDensity, d) supports:

source
BATBase.AnyIIDSampleable — Type
BAT.AnyIIDSampleable = Union{...}

Union of all distribution/density-like types that BAT can draw i.i.d. (independent and identically distributed) samples from:

source
BATBase.argchoice_msg — Function
argchoice_msg(f::Base.Callable, argname::Val, x)

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.

source
BATBase.bat_default — Function
bat_default(f::Base.Callable, argname::Symbol, objective...)
bat_default(f::Base.Callable, argname::Val, objective...)

Get the default value for argument argname of function f to use for objective(s).

objective(s) are mandatory arguments of function f that semantically constitute it's main objective(s), and that that a good default choice of optional arguments (e.g. choice of algorithm(s), etc.) may depend on. Which arguments are considered to be objectives is function-specific.

For example:

bat_default(bat_sample, :algorithm, density::PosteriorDensity) == MetropolisHastings()
bat_default(bat_sample, Val(:algorithm), samples::DensitySampleVector) == OrderedResampling()
source
BATBase.bat_eff_sample_size — Function
bat_eff_sample_size(
    v::Union{AbstractVector{<:Real},AbstractVectorOfSimilarVectors{<:Real}},
    [algorithm::EffSampleSizeAlgorithm]
)

bat_eff_sample_size(
    smpls::DensitySampleVector,
    [algorithm::EffSampleSizeAlgorithm]
)

Estimate effective sample size estimation for variate series v, resp. density samples smpls, separately for each degree of freedom.

Returns a NamedTuple of the shape

(result = eff_sample_size, ...)

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_eff_sample_size, add methods to bat_eff_sample_size_impl instead.

source
BATBase.bat_findmedian — Function
bat_findmedian(
    samples::DensitySampleVector
)

The function computes the median of marginalized samples.

Returns a NamedTuple of the shape

(result = v, ...)

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_findmedian, add methods to bat_findmedian_impl instead.

source
BATBase.bat_findmode — Function
bat_findmode(
    target::BAT.AnySampleable,
    [algorithm::BAT.AbstractModeEstimator]
)::DensitySampleVector

Estimate the global mode of target.

Returns a NamedTuple of the shape

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

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_findmode, add methods to bat_findmode_impl instead.

source
BATBase.bat_initval — Function
bat_initval(
    [rng::AbstractRNG,]
    target::BAT.AnyDensityLike,
    [algorithm::BAT.InitvalAlgorithm],
)::V

bat_initval(
    [rng::AbstractRNG,]
    target::BAT.AnyDensityLike,
    n::Integer,
    [algorithm::BAT.InitvalAlgorithm],
)::AbstractVector{<:V}

Generate one or n random initial/starting value(s) suitable for target.

Assuming the variates of target are of type T, returns a NamedTuple of the shape

(result = X::AbstractVector{T}, ...)

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_initval, add methods like

bat_initval_impl(rng::AbstractRNG, target::AnyDensityLike, algorithm::InitvalAlgorithm; kwargs...)
bat_initval_impl(rng::AbstractRNG, target::AnyDensityLike, n::Integer, algorithm::InitvalAlgorithm; kwargs...)

to bat_initval_impl instead.

source
BATBase.bat_integrate — Function
bat_integrate(
    target::AnySampleable,
    [algorithm::IntegrationAlgorithm]
)::DensitySampleVector

Calculate the integral (evidence) of target.

Returns a NamedTuple of the shape

(result = X::Measurements.Measurement, ...)

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_integrate, add methods to bat_integrate_impl instead.

source
BATBase.bat_integrated_autocorr_len — Function
bat_integrated_autocorr_len(
    v::Union{AbstractVector{<:Real},AbstractVectorOfSimilarVectors{<:Real}},
    algorithm::AutocorLenAlgorithm = GeyerAutocorLen()
)

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
BATBase.bat_sample — Function
bat_sample(
    [rng::AbstractRNG],
    target::BAT.AnySampleable,
    [algorithm::BAT.AbstractSamplingAlgorithm]
)::DensitySampleVector

Draw samples from target using algorithm.

Depending on sampling algorithm, the samples may be independent or correlated (e.g. when using MCMC).

Returns a NamedTuple of the shape

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

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_sample, add methods to bat_sample_impl instead.

source
BATBase.bat_transform — Function
bat_transform(
    target::AbstractDensityTransformTarget,
    density::AnyDensityLike,
    [algorithm::TransformAlgorithm]
)::AbstractDensity

Transform density to another variate space defined/implied by target.

Returns a NamedTuple of the shape

(result = newdensity::AbstractDensity, trafo = vartrafo::AbstractVariateTransform, ...)

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_transform, add methods to bat_transform_impl instead.

source
BATBase.bat_valgrad — Function
bat_valgrad(f::Function, [algorithm::DifferentiationAlgorithm])

Experimental feature, not part of stable public API.

Generated a function that calculates both value and gradient of f at given points.

The function f must support ValueShapes.varshape(f) and ValueShapes.unshaped(f).

Returns a NamedTuple of the shape

(result = valgrad_f, ...)

with

f_at_x, grad_of_f_at_x = valgrad_f(x)

grad_of_f_at_x = zero(x)
f_at_x = valgrad_f(!, grad_of_f_at_x, x)

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_valgrad, add methods to bat_valgrad_impl instead.

source
BATBase.eval_logval_unchecked — Function
BATBase.eval_logval_unchecked(density::AbstractDensity, v::Any)

Compute log of the value of a multivariate density function for the given variate/parameter-values.

Input:

  • density: density function
  • v: argument, i.e. variate / parameter-values

Note: If eval_logval_unchecked is called with an argument that is out of bounds, the behavior is undefined. The result for arguments that are not within bounds is implicitly -Inf, but it is the caller's responsibility to handle these cases.

source
BATBase.logdensityof — Function
logdensityof(density::AbstractDensity, v)::Real
logdensityof(density::AbstractDensity)::Function

Computes the logarithmic value of density at a given point, resp. returns a function that does so:

logdensityof(density, v) == logdensityof(density)(v)

The function returned by logdensityof(density) supports

(- logdensityof(density))(v) == - logdensityof(density)(v)

Note: This function should not be specialized for custom density types, implement BATBase.eval_logval_unchecked instead.

Note

This functionality is implemented in BAT.jl, not in BATBase.jl.

source
ValueShapes.totalndof — Method
ValueShapes.totalndof(density::AbstractDensity)::Union{Int,Missing}

Get the number of degrees of freedom of the variates of density. May return missing, if the shape of the variates is not fixed.

source
ValueShapes.varshape — Method
ValueShapes.varshape(
    density::AbstractDensity
)::Union{ValueShapes.AbstractValueShape,Missing}

ValueShapes.varshape(
    density::DistLikeDensity
)::ValueShapes.AbstractValueShape

Get the shapes of the variates of density.

For prior densities, the result must not be missing, but may be nothing if the prior only supports unshaped variate/parameter vectors.

source