Add to_samples and from_samples (#184)

Author: penelopeysm

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"

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

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