diff --git a/Project.toml b/Project.toml index 7c40ca91..173bfaab 100644 --- a/Project.toml +++ b/Project.toml @@ -3,7 +3,7 @@ uuid = "80f14c24-f653-4e6a-9b94-39d6b0f70001" keywords = ["markov chain monte carlo", "probabilistic programming"] license = "MIT" desc = "A lightweight interface for common MCMC methods." -version = "5.9.0" +version = "5.10.0" [deps] BangBang = "198e06fe-97b7-11e9-32a5-e1d131e6ad66" diff --git a/docs/src/api.md b/docs/src/api.md index 94b006ab..c24ddfa2 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -144,6 +144,13 @@ AbstractMCMC defines the abstract type `AbstractChains` for Markov chains. AbstractMCMC.AbstractChains ``` +The following two functions exist for converting `AbstractChains` from and to matrices of samples. + +```@docs +AbstractMCMC.to_samples +AbstractMCMC.from_samples +``` + For chains of this type, AbstractMCMC defines the following two methods. ```@docs diff --git a/src/AbstractMCMC.jl b/src/AbstractMCMC.jl index 185082a3..bceb04fd 100644 --- a/src/AbstractMCMC.jl +++ b/src/AbstractMCMC.jl @@ -30,6 +30,37 @@ parameter samples generated through a MCMC process. """ abstract type AbstractChains end +""" + AbstractMCMC.from_samples(::Type{T}, samples::Matrix) where {T<:AbstractChains} + +Convert a Matrix of parameter samples to an `AbstractChains` object. + +Methods of this function should be implemented with the signature listed above, and should +return a chain of type `T`. + +This function is the inverse of [`to_samples`](@ref). + +In general, it is expected that for `chains::Tchn`, `from_samples(Tchn, to_samples(Tsample, +chains))` contains data that are equivalent to that in `chains` (although differences in +e.g. metadata or ordering are permissible). + +Furthermore, the same should hold true for `to_samples(Tsample, from_samples(Tchn, +samples))` where `samples::Matrix{Tsample}`. +""" +function from_samples end + +""" + AbstractMCMC.to_samples(::Type{T}, chains::AbstractChains) where {T} + +Convert an `AbstractChains` object to an `Matrix` of parameter samples. + +Methods of this function should be implemented with the signature listed above, and should +return a `Matrix{T}`. + +See also: [`from_samples`](@ref). +""" +function to_samples end + """ AbstractSampler