API
Modules
Types and constants
BATBase.AbstractDensity
BATBase.AbstractDensitySample
BATBase.AbstractDensitySampleVector
BATBase.AbstractDensityTransformTarget
BATBase.AbstractDistributionDensity
BATBase.AbstractModeEstimator
BATBase.AbstractSampleGenerator
BATBase.AbstractSamplingAlgorithm
BATBase.AbstractTransformToInfinite
BATBase.AbstractTransformToUnitspace
BATBase.AnyDensityLike
BATBase.AnyIIDSampleable
BATBase.AnySampleable
BATBase.AutocorLenAlgorithm
BATBase.DensityIdentityTransform
BATBase.DifferentiationAlgorithm
BATBase.DistLikeDensity
BATBase.EffSampleSizeAlgorithm
BATBase.FullDensityTransform
BATBase.InitvalAlgorithm
BATBase.IntegrationAlgorithm
BATBase.NoDensityTransform
BATBase.PriorSubstitution
BATBase.PriorToGaussian
BATBase.PriorToUniform
BATBase.TransformAlgorithm
Functions and macros
BATBase.argchoice_msg
BATBase.bat_default
BATBase.bat_eff_sample_size
BATBase.bat_findmedian
BATBase.bat_findmode
BATBase.bat_initval
BATBase.bat_integrate
BATBase.bat_integrated_autocorr_len
BATBase.bat_sample
BATBase.bat_transform
BATBase.bat_valgrad
BATBase.eval_logval_unchecked
BATBase.logdensityof
ValueShapes.totalndof
ValueShapes.varshape
Documentation
BATBase.BATBase
— ModuleBATBase
Template for Julia packages.
BATBase.AbstractDensity
— Typeabstract 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)
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.
BATBase.AbstractDensitySample
— Typeabstract 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 oflogdensityof(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.
BATBase.AbstractDensitySampleVector
— Typeabstract 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.
BATBase.AbstractDensityTransformTarget
— Typeabstract type AbstractDensityTransformTarget
Abstract type for probability density transformation targets.
BATBase.AbstractDistributionDensity
— Typeabstract 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)
.
This functionality is implemented in BAT.jl, not in BATBase.jl.
BATBase.AbstractModeEstimator
— Typeabstract type BAT.AbstractModeEstimator
Abstract type for BAT optimization algorithms.
A typical application for optimization in BAT is mode estimation (see bat_findmode
),
BATBase.AbstractSampleGenerator
— Typeabstract type AbstractSampleGenerator
BAT-internal, not part of stable public API.
Abstract super type for sample generators.
BATBase.AbstractSamplingAlgorithm
— Typeabstract type BAT.AbstractSamplingAlgorithm
Abstract type for BAT sampling algorithms. See bat_sample
.
BATBase.AbstractTransformToInfinite
— Typeabstract 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.
BATBase.AbstractTransformToUnitspace
— Typeabstract type AbstractTransformToUnitspace <: AbstractDensityTransformTarget
Abstract type for density transformation targets that specify a transformation into the unit hypercube.
BATBase.AutocorLenAlgorithm
— Typeabstract type AutocorLenAlgorithm
Abstract type for integrated autocorrelation length estimation algorithms.
BATBase.DensityIdentityTransform
— Typestruct DensityIdentityTransform <: TransformAlgorithm
A no-op density transform algorithm that leaves any density unchanged.
Constructors:
DensityIdentityTransform()
BATBase.DifferentiationAlgorithm
— Typeabstract type DifferentiationAlgorithm
Experimental feature, not part of stable public API.
Abstract type for integrated autocorrelation length estimation algorithms.
BATBase.DistLikeDensity
— Typeabstract 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)
The function BAT.var_bounds
is not part of the stable public BATBase.jl and BAT.jl APIs and subject to change without deprecation.
BATBase.EffSampleSizeAlgorithm
— Typeabstract type EffSampleSizeAlgorithm
Abstract type for integrated autocorrelation length estimation algorithms.
BATBase.FullDensityTransform
— Typestruct 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()
BATBase.InitvalAlgorithm
— Typeabstract type BAT.InitvalAlgorithm
Abstract type for BAT initial/starting value generation algorithms.
Many algorithms in BAT, like MCMC and optimization, need initial/starting values.
BATBase.IntegrationAlgorithm
— Typeabstract type IntegrationAlgorithm
Abstract type for integration algorithms.
BATBase.NoDensityTransform
— Typestruct NoDensityTransform <: AbstractDensityTransformTarget
The identity density transformation target, specifies that densities should not be transformed.
Constructors:
NoDensityTransform()
BATBase.PriorSubstitution
— Typestruct 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()
BATBase.PriorToGaussian
— Typestruct 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()
BATBase.PriorToUniform
— Typestruct 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()
BATBase.TransformAlgorithm
— Typeabstract type TransformAlgorithm
Abstract type for density transformation algorithms.
BATBase.AnyDensityLike
— TypeBAT.AnyDensityLike = Union{...}
Union of all types that BAT will accept as a probability density, resp. that convert(AbstractDensity, d)
supports:
AbstractDensity
Distributions.Distribution
BATBase.AnyIIDSampleable
— TypeBAT.AnyIIDSampleable = Union{...}
Union of all distribution/density-like types that BAT can draw i.i.d. (independent and identically distributed) samples from:
DistLikeDensity
Distributions.Distribution
BATBase.AnySampleable
— TypeBAT.AnySampleable = Union{...}
Union of all types that BAT can sample from:
AbstractDensity
AbstractDensitySampleVector
Distributions.Distribution
BATBase.argchoice_msg
— Functionargchoice_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
.
BATBase.bat_default
— Functionbat_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()
BATBase.bat_eff_sample_size
— Functionbat_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.
Do not add add methods to bat_eff_sample_size
, add methods to bat_eff_sample_size_impl
instead.
BATBase.bat_findmedian
— Functionbat_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.
Do not add add methods to bat_findmedian
, add methods to bat_findmedian_impl
instead.
BATBase.bat_findmode
— Functionbat_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.
Do not add add methods to bat_findmode
, add methods to bat_findmode_impl
instead.
BATBase.bat_initval
— Functionbat_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.
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.
BATBase.bat_integrate
— Functionbat_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.
Do not add add methods to bat_integrate
, add methods to bat_integrate_impl
instead.
BATBase.bat_integrated_autocorr_len
— Functionbat_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.
Do not add add methods to bat_integrated_autocorr_len
, add methods to bat_integrated_autocorr_len_impl
instead.
BATBase.bat_sample
— Functionbat_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.
Do not add add methods to bat_sample
, add methods to bat_sample_impl
instead.
BATBase.bat_transform
— Functionbat_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.
Do not add add methods to bat_transform
, add methods to bat_transform_impl
instead.
BATBase.bat_valgrad
— Functionbat_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.
Do not add add methods to bat_valgrad
, add methods to bat_valgrad_impl
instead.
BATBase.eval_logval_unchecked
— FunctionBATBase.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 functionv
: 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.
BATBase.logdensityof
— Functionlogdensityof(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.
This functionality is implemented in BAT.jl, not in BATBase.jl.
ValueShapes.totalndof
— MethodValueShapes.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.
ValueShapes.varshape
— MethodValueShapes.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.