API
AbstractMCMC defines an interface for sampling Markov chains.
Model
AbstractMCMC.AbstractModel
— TypeAbstractModel
An AbstractModel
represents a generic model type that can be used to perform inference.
AbstractMCMC.LogDensityModel
— TypeLogDensityModel <: AbstractMCMC.AbstractModel
Wrapper around something that implements the LogDensityProblem.jl interface.
Note that this does not implement the LogDensityProblems.jl interface itself, but it simply useful for indicating to the sample
and other AbstractMCMC
methods that the wrapped object implements the LogDensityProblems.jl interface.
Fields
logdensity
: The object that implements the LogDensityProblems.jl interface.
Sampler
AbstractMCMC.AbstractSampler
— TypeAbstractSampler
The AbstractSampler
type is intended to be inherited from when implementing a custom sampler. Any persistent state information should be saved in a subtype of AbstractSampler
.
When defining a new sampler, you should also overload the function transition_type
, which tells the sample
function what type of parameter it should expect to receive.
Sampling a single chain
StatsBase.sample
— Methodsample(
+API · AbstractMCMC API
AbstractMCMC defines an interface for sampling Markov chains.
Model
AbstractMCMC.AbstractModel
— TypeAbstractModel
An AbstractModel
represents a generic model type that can be used to perform inference.
sourceAbstractMCMC.LogDensityModel
— TypeLogDensityModel <: AbstractMCMC.AbstractModel
Wrapper around something that implements the LogDensityProblem.jl interface.
Note that this does not implement the LogDensityProblems.jl interface itself, but it simply useful for indicating to the sample
and other AbstractMCMC
methods that the wrapped object implements the LogDensityProblems.jl interface.
Fields
logdensity
: The object that implements the LogDensityProblems.jl interface.
sourceSampler
AbstractMCMC.AbstractSampler
— TypeAbstractSampler
The AbstractSampler
type is intended to be inherited from when implementing a custom sampler. Any persistent state information should be saved in a subtype of AbstractSampler
.
When defining a new sampler, you should also overload the function transition_type
, which tells the sample
function what type of parameter it should expect to receive.
sourceSampling a single chain
StatsBase.sample
— Methodsample(
rng::Random.AbatractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler,
N_or_isdone;
kwargs...,
-)
Sample from the model
with the Markov chain Monte Carlo sampler
and return the samples.
If N_or_isdone
is an Integer
, exactly N_or_isdone
samples are returned.
Otherwise, sampling is performed until a convergence criterion N_or_isdone
returns true
. The convergence criterion has to be a function with the signature
isdone(rng, model, sampler, samples, state, iteration; kwargs...)
where state
and iteration
are the current state and iteration of the sampler, respectively. It should return true
when sampling should end, and false
otherwise.
Keyword arguments
See https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.
sourceStatsBase.sample
— Methodsample(
+)
Sample from the model
with the Markov chain Monte Carlo sampler
and return the samples.
If N_or_isdone
is an Integer
, exactly N_or_isdone
samples are returned.
Otherwise, sampling is performed until a convergence criterion N_or_isdone
returns true
. The convergence criterion has to be a function with the signature
isdone(rng, model, sampler, samples, state, iteration; kwargs...)
where state
and iteration
are the current state and iteration of the sampler, respectively. It should return true
when sampling should end, and false
otherwise.
Keyword arguments
See https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.
sourceStatsBase.sample
— Methodsample(
rng::Random.AbstractRNG=Random.default_rng(),
logdensity,
sampler::AbstractSampler,
N_or_isdone;
kwargs...,
-)
Wrap the logdensity
function in a LogDensityModel
, and call sample
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceIterator
AbstractMCMC.steps
— Methodsteps(
+)
Wrap the logdensity
function in a LogDensityModel
, and call sample
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceIterator
AbstractMCMC.steps
— Methodsteps(
rng::Random.AbstractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler;
@@ -28,12 +28,12 @@
julia> iterator = steps(MyModel(), MySampler());
julia> collect(Iterators.take(iterator, 10)) == zeros(10)
-true
sourceAbstractMCMC.steps
— Methodsteps(
+true
sourceAbstractMCMC.steps
— Methodsteps(
rng::Random.AbstractRNG=Random.default_rng(),
logdensity,
sampler::AbstractSampler;
kwargs...,
-)
Wrap the logdensity
function in a LogDensityModel
, and call steps
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceTransducer
AbstractMCMC.Sample
— MethodSample(
+)
Wrap the logdensity
function in a LogDensityModel
, and call steps
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceTransducer
AbstractMCMC.Sample
— MethodSample(
rng::Random.AbstractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler;
@@ -50,12 +50,12 @@
julia> transducer = Sample(MyModel(), MySampler());
julia> collect(transducer(1:10)) == zeros(10)
-true
sourceAbstractMCMC.Sample
— MethodSample(
+true
sourceAbstractMCMC.Sample
— MethodSample(
rng::Random.AbstractRNG=Random.default_rng(),
logdensity,
sampler::AbstractSampler;
kwargs...,
-)
Wrap the logdensity
function in a LogDensityModel
, and call Sample
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceSampling multiple chains in parallel
StatsBase.sample
— Methodsample(
+)
Wrap the logdensity
function in a LogDensityModel
, and call Sample
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceSampling multiple chains in parallel
StatsBase.sample
— Methodsample(
rng::Random.AbstractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler,
@@ -63,7 +63,7 @@
N::Integer,
nchains::Integer;
kwargs...,
-)
Sample nchains
Monte Carlo Markov chains from the model
with the sampler
in parallel using the parallel
algorithm, and combine them into a single chain.
Keyword arguments
See https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.
sourceStatsBase.sample
— Methodsample(
+)
Sample nchains
Monte Carlo Markov chains from the model
with the sampler
in parallel using the parallel
algorithm, and combine them into a single chain.
Keyword arguments
See https://turinglang.org/AbstractMCMC.jl/dev/api/#Common-keyword-arguments for common keyword arguments.
sourceStatsBase.sample
— Methodsample(
rng::Random.AbstractRNG=Random.default_rng(),
logdensity,
sampler::AbstractSampler,
@@ -71,4 +71,4 @@
N::Integer,
nchains::Integer;
kwargs...,
-)
Wrap the logdensity
function in a LogDensityModel
, and call sample
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
sourceTwo algorithms are provided for parallel sampling with multiple threads and multiple processes, and one allows for the user to sample multiple chains in serial (no parallelization):
AbstractMCMC.MCMCThreads
— TypeMCMCThreads
The MCMCThreads
algorithm allows users to sample MCMC chains in parallel using multiple threads.
sourceAbstractMCMC.MCMCDistributed
— TypeMCMCDistributed
The MCMCDistributed
algorithm allows users to sample MCMC chains in parallel using multiple processes.
sourceAbstractMCMC.MCMCSerial
— TypeMCMCSerial
The MCMCSerial
algorithm allows users to sample serially, with no thread or process parallelism.
sourceCommon keyword arguments
Common keyword arguments for regular and parallel sampling are:
progress
(default: AbstractMCMC.PROGRESS[]
which is true
initially): toggles progress loggingchain_type
(default: Any
): determines the type of the returned chaincallback
(default: nothing
): if callback !== nothing
, then callback(rng, model, sampler, sample, iteration)
is called after every sampling step, where sample
is the most recent sample of the Markov chain and iteration
is the current iterationnum_warmup
(default: 0
): number of "warm-up" steps to take before the first "regular" step, i.e. number of times to call AbstractMCMC.step_warmup
before the first call to AbstractMCMC.step
.discard_initial
(default: num_warmup
): number of initial samples that are discarded. Note that if discard_initial < num_warmup
, warm-up samples will also be included in the resulting samples.thinning
(default: 1
): factor by which to thin samples.initial_state
(default: nothing
): if initial_state !== nothing
, the first call to AbstractMCMC.step
is passed initial_state
as the state
argument.
Info The common keyword arguments progress
, chain_type
, and callback
are not supported by the iterator AbstractMCMC.steps
and the transducer AbstractMCMC.Sample
.
There is no "official" way for providing initial parameter values yet. However, multiple packages such as EllipticalSliceSampling.jl and AdvancedMH.jl support an initial_params
keyword argument for setting the initial values when sampling a single chain. To ensure that sampling multiple chains "just works" when sampling of a single chain is implemented, we decided to support initial_params
in the default implementations of the ensemble methods:
initial_params
(default: nothing
): if initial_params isa AbstractArray
, then the i
th element of initial_params
is used as initial parameters of the i
th chain. If one wants to use the same initial parameters x
for every chain, one can specify e.g. initial_params = FillArrays.Fill(x, N)
.
Progress logging can be enabled and disabled globally with AbstractMCMC.setprogress!(progress)
.
AbstractMCMC.setprogress!
— Functionsetprogress!(progress::Bool)
Enable progress logging globally if progress
is true
, and disable it otherwise.
sourceChains
The chain_type
keyword argument allows to set the type of the returned chain. A common choice is to return chains of type Chains
from MCMCChains.jl.
AbstractMCMC defines the abstract type AbstractChains
for Markov chains.
AbstractMCMC.AbstractChains
— TypeAbstractChains
AbstractChains
is an abstract type for an object that stores parameter samples generated through a MCMC process.
sourceFor chains of this type, AbstractMCMC defines the following two methods.
AbstractMCMC.chainscat
— Functionchainscat(c::AbstractChains...)
Concatenate multiple chains.
By default, the chains are concatenated along the third dimension by calling cat(c...; dims=3)
.
sourceAbstractMCMC.chainsstack
— Functionchainsstack(c::AbstractVector)
Stack chains in c
.
By default, the vector of chains is returned unmodified. If eltype(c) <: AbstractChains
, then reduce(chainscat, c)
is called.
sourceSettings
This document was generated with Documenter.jl version 1.1.2 on Wednesday 25 October 2023. Using Julia version 1.9.3.
+)
Wrap the logdensity
function in a LogDensityModel
, and call sample
with the resulting model instead of logdensity
.
The logdensity
function has to support the LogDensityProblems.jl interface.
Two algorithms are provided for parallel sampling with multiple threads and multiple processes, and one allows for the user to sample multiple chains in serial (no parallelization):
AbstractMCMC.MCMCThreads
— TypeMCMCThreads
The MCMCThreads
algorithm allows users to sample MCMC chains in parallel using multiple threads.
AbstractMCMC.MCMCDistributed
— TypeMCMCDistributed
The MCMCDistributed
algorithm allows users to sample MCMC chains in parallel using multiple processes.
AbstractMCMC.MCMCSerial
— TypeMCMCSerial
The MCMCSerial
algorithm allows users to sample serially, with no thread or process parallelism.
Common keyword arguments
Common keyword arguments for regular and parallel sampling are:
progress
(default:AbstractMCMC.PROGRESS[]
which istrue
initially): toggles progress loggingchain_type
(default:Any
): determines the type of the returned chaincallback
(default:nothing
): ifcallback !== nothing
, thencallback(rng, model, sampler, sample, iteration)
is called after every sampling step, wheresample
is the most recent sample of the Markov chain anditeration
is the current iterationnum_warmup
(default:0
): number of "warm-up" steps to take before the first "regular" step, i.e. number of times to callAbstractMCMC.step_warmup
before the first call toAbstractMCMC.step
.discard_initial
(default:num_warmup
): number of initial samples that are discarded. Note that ifdiscard_initial < num_warmup
, warm-up samples will also be included in the resulting samples.thinning
(default:1
): factor by which to thin samples.initial_state
(default:nothing
): ifinitial_state !== nothing
, the first call toAbstractMCMC.step
is passedinitial_state
as thestate
argument.
The common keyword arguments progress
, chain_type
, and callback
are not supported by the iterator AbstractMCMC.steps
and the transducer AbstractMCMC.Sample
.
There is no "official" way for providing initial parameter values yet. However, multiple packages such as EllipticalSliceSampling.jl and AdvancedMH.jl support an initial_params
keyword argument for setting the initial values when sampling a single chain. To ensure that sampling multiple chains "just works" when sampling of a single chain is implemented, we decided to support initial_params
in the default implementations of the ensemble methods:
initial_params
(default:nothing
): ifinitial_params isa AbstractArray
, then thei
th element ofinitial_params
is used as initial parameters of thei
th chain. If one wants to use the same initial parametersx
for every chain, one can specify e.g.initial_params = FillArrays.Fill(x, N)
.
Progress logging can be enabled and disabled globally with AbstractMCMC.setprogress!(progress)
.
AbstractMCMC.setprogress!
— Functionsetprogress!(progress::Bool)
Enable progress logging globally if progress
is true
, and disable it otherwise.
Chains
The chain_type
keyword argument allows to set the type of the returned chain. A common choice is to return chains of type Chains
from MCMCChains.jl.
AbstractMCMC defines the abstract type AbstractChains
for Markov chains.
AbstractMCMC.AbstractChains
— TypeAbstractChains
AbstractChains
is an abstract type for an object that stores parameter samples generated through a MCMC process.
For chains of this type, AbstractMCMC defines the following two methods.
AbstractMCMC.chainscat
— Functionchainscat(c::AbstractChains...)
Concatenate multiple chains.
By default, the chains are concatenated along the third dimension by calling cat(c...; dims=3)
.
AbstractMCMC.chainsstack
— Functionchainsstack(c::AbstractVector)
Stack chains in c
.
By default, the vector of chains is returned unmodified. If eltype(c) <: AbstractChains
, then reduce(chainscat, c)
is called.