Add BAT.jl API definition and initial tests

Project.toml

@@ -3,12 +3,26 @@ uuid = "b4d2a721-a957-46f4-b6b6-f139c9e7db21"
 version = "0.1.0"
 
 [deps]
+ArraysOfArrays = "65a8f2f4-9b39-5baf-92e2-a9cc46fdf018"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+ValueShapes = "136a8f8c-c49b-4edb-8b98-f3d64d48be8f"
+
 
 [compat]
-julia = "1"
+ArraysOfArrays = "0.4, 0.5"
+Distributions = "0.21, 0.22, 0.23, 0.24"
+DocStringExtensions = "0.8"
+StatsBase = "0.32, 0.33"
+StructArrays = "0.4, 0.5"
+ValueShapes = "0.8"
+julia = "1.3"
 
 [extras]
+StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["StructArrays", "Test"]

README.md

@@ -11,3 +11,11 @@
 
 * [Documentation for stable version](https://bat.github.io/BATBase.jl/stable)
 * [Documentation for development version](https://bat.github.io/BATBase.jl/dev)
+
+**Note: Integration of BATBase.jl with BAT.jl is not complete yet.**
+
+BATBase.jl contains the core interface definition of [BAT.jl](https://github.com/bat/BAT.jl).
+
+BATBase.jl will serve as a lightweight and low-dependency package that packages
+implementing BAT-compatible densities and algorithms can depend on instead
+of the full BAT.jl.

docs/src/index.md

@@ -1 +1,9 @@
 # BATBase.jl
+
+**Note: Integration of BATBase.jl with BAT.jl is not complete yet.**
+
+BATBase.jl contains the core interface definition of [BAT.jl](https://github.com/bat/BAT.jl).
+
+BATBase.jl will serve as a lightweight and low-dependency package that packages
+implementing BAT-compatible densities and algorithms can depend on instead
+of the full BAT.jl.

src/BATBase.jl

@@ -9,6 +9,15 @@ Template for Julia packages.
 """
 module BATBase
 
-include("hello_world.jl")
+using Random
+
+using ArraysOfArrays
+using Distributions
+using DocStringExtensions
+using StatsBase
+using ValueShapes
+
+include("basetypes/basetypes.jl")
+include("algotypes/algotypes.jl")
 
 end # module

src/algotypes/algotypes.jl

@@ -0,0 +1,12 @@
+# This file is a part of BATBase.jl, licensed under the MIT License (MIT).
+
+include("bat_default.jl")
+include("initval_algorithm.jl")
+include("transform_algorithm.jl")
+include("sampling_algorithm.jl")
+include("autocor_len.jl")
+include("eff_sample_size.jl")
+include("mode_estimator.jl")
+include("median_estimator.jl")
+include("differentiation_algorithm.jl")
+include("integration_algorithm.jl")

src/algotypes/autocor_len.jl

@@ -0,0 +1,54 @@
+# This file is a part of BATBase.jl, licensed under the MIT License (MIT).
+
+
+"""
+    abstract type AutocorLenAlgorithm
+
+Abstract type for integrated autocorrelation length estimation algorithms.
+"""
+abstract type AutocorLenAlgorithm end
+export AutocorLenAlgorithm
+
+
+
+"""
+    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
+
+```julia
+(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.
+"""
+function bat_integrated_autocorr_len end
+export bat_integrated_autocorr_len
+
+function bat_integrated_autocorr_len_impl end
+
+
+function bat_integrated_autocorr_len(
+    v::Union{AbstractVector{<:Real},AbstractVectorOfSimilarVectors{<:Real}},
+    algorithm = bat_default_withdebug(bat_integrated_autocorr_len, Val(:algorithm), v)
+)
+    r = bat_integrated_autocorr_len_impl(v, algorithm)
+    result_with_args(r, (algorithm = algorithm,))
+end
+
+
+function argchoice_msg(::typeof(bat_integrated_autocorr_len), ::Val{:algorithm}, x::AutocorLenAlgorithm)
+    "Using integrated autocorrelation length estimator $x"
+end

src/algotypes/bat_default.jl

@@ -0,0 +1,60 @@
+# This file is a part of BATBase.jl, licensed under the MIT License (MIT).
+
+"""
+    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:
+
+```julia
+bat_default(bat_sample, :algorithm, density::PosteriorDensity) == MetropolisHastings()
+bat_default(bat_sample, Val(:algorithm), samples::DensitySampleVector) == OrderedResampling()
+```
+"""
+function bat_default end
+export bat_default
+
+@inline bat_default(f::Base.Callable, argname::Symbol, objective...) = bat_default(f, Val{argname}(), objective...)
+
+
+
+"""
+    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`](@ref).
+"""
+function argchoice_msg end
+
+
+function bat_default_withinfo(f::Base.Callable, argname::Val, objective...)
+    default = bat_default(f::Base.Callable, argname::Val, objective...)
+    @info argchoice_msg(f, argname::Val, default)
+    default
+end
+
+function bat_default_withdebug(f::Base.Callable, argname::Val, objective...)
+    default = bat_default(f::Base.Callable, argname::Val, objective...)
+    @debug argchoice_msg(f, argname::Val, default)
+    default
+end
+
+
+
+result_with_args(r::NamedTuple) = merge(r, (optargs = NamedTuple(), kwargs = NamedTuple()))
+
+result_with_args(r::NamedTuple, optargs::NamedTuple) = merge(r, (optargs = optargs, kwargs = NamedTuple()))
+
+result_with_args(r::NamedTuple, optargs::NamedTuple, kwargs::NamedTuple) = merge(r, (optargs = optargs, kwargs = kwargs))
+
+result_with_args(r::NamedTuple, optargs::NamedTuple, kwargs::Base.Iterators.Pairs) = result_with_args(r, optargs, values(kwargs))

src/algotypes/differentiation_algorithm.jl

@@ -0,0 +1,76 @@
+# This file is a part of BATBase.jl, licensed under the MIT License (MIT).
+
+
+"""
+    abstract type DifferentiationAlgorithm
+
+*Experimental feature, not part of stable public API.*
+
+Abstract type for integrated autocorrelation length estimation algorithms.
+"""
+abstract type DifferentiationAlgorithm end
+export DifferentiationAlgorithm
+
+
+
+"""
+    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
+
+```julia
+(result = valgrad_f, ...)
+```
+
+with
+
+```julia
+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.
+"""
+function bat_valgrad end
+export bat_valgrad
+
+function bat_valgrad_impl end
+
+
+function bat_valgrad(
+    f::Function,
+    algorithm = bat_default_withdebug(bat_valgrad, Val(:algorithm), f)
+)
+    r = bat_valgrad_impl(f, algorithm)
+    result_with_args(r, (algorithm = algorithm,))
+end
+
+
+function argchoice_msg(::typeof(bat_valgrad), ::Val{:algorithm}, x::DifferentiationAlgorithm)
+    "Using automiatic differentiation algorithm $x"
+end
+
+
+
+# ToDo, move to BAT.jl:
+#=
+gradient_shape(vs::AbstractValueShape) = replace_const_shapes(ValueShapes.const_zero_shape, vs)
+
+abstract type GradientFunction end
+=#

src/algotypes/eff_sample_size.jl

@@ -0,0 +1,69 @@
+# This file is a part of BATBase.jl, licensed under the MIT License (MIT).
+
+
+"""
+    abstract type EffSampleSizeAlgorithm
+
+Abstract type for integrated autocorrelation length estimation algorithms.
+"""
+abstract type EffSampleSizeAlgorithm end
+export EffSampleSizeAlgorithm
+
+
+
+"""
+    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
+
+```julia
+(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.
+"""
+function bat_eff_sample_size end
+export bat_eff_sample_size
+
+function bat_eff_sample_size_impl end
+
+
+function bat_eff_sample_size(
+    v::Union{AbstractVector{<:Real},AbstractVectorOfSimilarVectors{<:Real}},
+    algorithm = bat_default_withdebug(bat_eff_sample_size, Val(:algorithm), v)
+)
+    r = bat_eff_sample_size_impl(v, algorithm)
+    result_with_args(r, (algorithm = algorithm,))
+end
+
+
+function bat_eff_sample_size(
+    smpls::AbstractDensitySampleVector,
+    algorithm = bat_default_withdebug(bat_eff_sample_size, Val(:algorithm), smpls);
+    kwargs...
+)
+    r = bat_eff_sample_size_impl(smpls, algorithm; kwargs...)
+    result_with_args(r, (algorithm = algorithm,))
+end
+
+
+function argchoice_msg(::typeof(bat_eff_sample_size), ::Val{:algorithm}, x::EffSampleSizeAlgorithm)
+    "Using integrated autocorrelation length estimator $x"
+end