# API

AbstractMCMC defines an interface for sampling Markov chains.

## Model

`AbstractMCMC.AbstractModel`

— Type`AbstractModel`

An `AbstractModel`

represents a generic model type that can be used to perform inference.

`AbstractMCMC.LogDensityModel`

— Type`LogDensityModel <: 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`

— Type`AbstractSampler`

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`

— Method```
sample(
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.

`StatsBase.sample`

— Method```
sample(
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.

### Iterator

`AbstractMCMC.steps`

— Method```
steps(
rng::Random.AbstractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler;
kwargs...,
)
```

Create an iterator that returns samples from the `model`

with the Markov chain Monte Carlo `sampler`

.

**Examples**

```
julia> struct MyModel <: AbstractMCMC.AbstractModel end
julia> struct MySampler <: AbstractMCMC.AbstractSampler end
julia> function AbstractMCMC.step(rng, ::MyModel, ::MySampler, state=nothing; kwargs...)
# all samples are zero
return 0.0, state
end
julia> iterator = steps(MyModel(), MySampler());
julia> collect(Iterators.take(iterator, 10)) == zeros(10)
true
```

`AbstractMCMC.steps`

— Method```
steps(
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.

### Transducer

`AbstractMCMC.Sample`

— Method```
Sample(
rng::Random.AbstractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler;
kwargs...,
)
```

Create a transducer that returns samples from the `model`

with the Markov chain Monte Carlo `sampler`

.

**Examples**

```
julia> struct MyModel <: AbstractMCMC.AbstractModel end
julia> struct MySampler <: AbstractMCMC.AbstractSampler end
julia> function AbstractMCMC.step(rng, ::MyModel, ::MySampler, state=nothing; kwargs...)
# all samples are zero
return 0.0, state
end
julia> transducer = Sample(MyModel(), MySampler());
julia> collect(transducer(1:10)) == zeros(10)
true
```

`AbstractMCMC.Sample`

— Method```
Sample(
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.

## Sampling multiple chains in parallel

`StatsBase.sample`

— Method```
sample(
rng::Random.AbstractRNG=Random.default_rng(),
model::AbstractModel,
sampler::AbstractSampler,
parallel::AbstractMCMCEnsemble,
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.

`StatsBase.sample`

— Method```
sample(
rng::Random.AbstractRNG=Random.default_rng(),
logdensity,
sampler::AbstractSampler,
parallel::AbstractMCMCEnsemble,
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.

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`

— Type`MCMCThreads`

The `MCMCThreads`

algorithm allows users to sample MCMC chains in parallel using multiple threads.

`AbstractMCMC.MCMCDistributed`

— Type`MCMCDistributed`

The `MCMCDistributed`

algorithm allows users to sample MCMC chains in parallel using multiple processes.

`AbstractMCMC.MCMCSerial`

— Type`MCMCSerial`

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 is`true`

initially): toggles progress logging`chain_type`

(default:`Any`

): determines the type of the returned chain`callback`

(default:`nothing`

): if`callback !== nothing`

, then`callback(rng, model, sampler, sample, state, iteration)`

is called after every sampling step, where`sample`

is the most recent sample of the Markov chain and`state`

and`iteration`

are the current state and iteration of the sampler`discard_initial`

(default:`0`

): number of initial samples that are discarded`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.

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!`

— Function`setprogress!(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`

— Type`AbstractChains`

`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`

— Function`chainscat(c::AbstractChains...)`

Concatenate multiple chains.

By default, the chains are concatenated along the third dimension by calling `cat(c...; dims=3)`

.

`AbstractMCMC.chainsstack`

— Function`chainsstack(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.