Index

AdaptationUnifRW(θ::K; kwargs...) where K

Define an adaptation scheme for a random walker that does updates on the parameter of shape and type θ. The following named parameters can be specified

Arguments

• adapt_every_k_steps=100: number of steps based on which adaptation happens
• target_accpt_rate=0.234: acceptance rate of MH step that is to be targetted
• scale=1.0: scaling of the adaptation
• min=1e-12: minimum allowable (half)-range of the uniform sampler
• max=1e7: maximum allowable (half)-range of the unifor sampler
• offset=1e2: number of adaptation steps after which the shrinking of adaptive steps is supposed to start.

mutable struct GenericChainStats{T} <: ChainStats
    rolling_ar::Vector{Vector{Float64}}
    roll_window::Int64
    mean::Vector{T}
    cov::Matrix{T}
    N::Int64
end

Simple online statistics for the Markov chain.

GenericMCMCBackend <: MCMCBackend

A flag that no specific backend is passed.

NoAdaptation

A struct-flag for indicating that no adaptation is to be done.

get_decorators(updt_and_decor)

Retrieve all decorators from a list

isdecorator(u)

Returns true if u is a subtype of decorators.

run!(
    mcmc::MCMC, num_mcmc_steps, data, θinit, callbacks=Callback[];
    kwargs...
)

The main calling function of this package that initializes, runs and outputs the results of an MCMC sampler for discretely observed stochastic processes.

Arguments

• mcmc::MCMC: specifies a sequence of updates that constitute a single MCMC step and provides additional info about the MCMC backend algorithm to be used
• num_mcmc_steps: the total number of MCMC steps
• data: completely characterizes everything that is known about the observations (including everything known about the underlying dynamics and the way it was collected),
• θinit: an initial guess for the unknown parameters
• callbacks: a collection of extra utility functions that do extra work around MCMC sampling.
• exclude_updates: a standard named argument which lists the update indices and corresponding ranges of MCMC iterations at which given updates are supposed to be omitted.
• kwargs...: additional named arguments, passed onto initializers of global workspace; they depend on the chosen MCMCBackend

Supertype for all adaptation schemes.

MCMCConjugateParamUpdate <: MCMCParamUpdate

Supertype of all conjugate updates that update parameters and for which sampling can be done directly, without resorting to a Metropolis-Hastings algorithm

MCMCConjugateUpdate <: MCMCUpdate

Supertype of all conjugate updates, for which sampling can be done directly, without resorting to a Metropolis-Hastings algorithm

MCMCGradientBasedUpdate <: MCMCParamUpdate

Supertype of all updates that require local gradient information to perform update of state.

MCMCImputation <: MCMCUpdate

Supertype of all updates that do not make any changes to the main parameter state in GlobalWorkspace, but instead, perform sampling on any auxiliary variables that are not of direct interest to the MCMC chain.

MCMCParamUpdate <: MCMCUpdate

Supertype of all updates that make changes to the main MCMC parameter called state in the GlobalWorkspace.

Supertype of all MCMC updates

Supertype of all decorators to update schemes. In this context, we use the word decorator to refer to any additional information that needs to be conveyed to the MCMC sampler that is not directly extractable from the update-objects themselves (for instance, a change in the delimitation of blocks that is made in-between updates).

RandomWalk <: TransitionKernel

Supertype for all random walkers.

Supertype of all transition kernels that perform updates on the main state of the global workspace. Conceptually, these are used by subtypes of MCMCParamUpdate to perform actual sampling and instances of types inheriting from TransitionKernel are usually member objects of the instances inheriting from MCMCParamUpdate.

Base.:(==)(a::AdaptationUnifRW{T}, b::AdaptationUnifRW{S}) where{T,S}

Convenience comparison of AdaptationUnifRW instances. Used only for tests.

Base.iterate(iter::MCMCSchedule, state=iter.start)

Iterate through the MCMCSchedule, outputting the named tuples (mcmciter=..., pidx=...) along the way, indicating the current index of the mcmc sampler (mcmciter), as well as the index of update that is to be performed.

Base.rand(rw::UniformRandomWalk, θ)

Sample a new state for a random walker rw that is currently in a state θ.

reset!(adpt::AdaptationUnifRW)

Reset the number of proposals and accepted samples to zero.

Distributions.logpdf(rw::UniformRandomWalk, θ, θ°)

Evaluate the log-probability density function for a move of a random walker from θ to θ°.

logpdf(::Prior, θ)

Evaluate the log-probability density function at θ for a given prior.

_AdaptationUnifRW(
        ::Any, ::Val{:scalar}, ::Val{N}, trgt_ar, steps; kwargs...
    ) where N

Internal constructor of AdaptationUnifRW, populating entries with scalars.

_AdaptationUnifRW(
        ::Val{false}, ::Val{:nonscalar}, v::Val{N}, trgt_ar, steps; kwargs...
    ) where N

Internal constructor of AdaptationUnifRW, populating entries with SVectors.

_AdaptationUnifRW(
        ::Val{true}, ::Val{:nonscalar}, ::Val{N}, trgt_ar, steps; kwargs...
    ) where N

Internal constructor of AdaptationUnifRW, populating entries with vectors.

__run!(global_ws, local_wss, updates, schedule, callbacks)

Internal loops that run the (already initialized) MCMC sampler. global_ws and local_wss are the already initialized global workspace and local workspaces (one for each update) respectively. schedule is the iterator over MCMC steps and callbacks is a list of callbacks.

_adpt_rw_fill_defaults(N; kwargs...)

Return a vector with set vector parameters, falling back on default values if necessary.

_adpt_rw_fill_defaults(f::Function)

Return a vector with set parameters, setting them according to the "recipe" f, falling back on default values if necessary.

_adpt_rw_fill_defaults(; kwargs...)

Return a vector with set scalar parameters, falling back on default values if necessary.

_adpt_rw_fill_defaults(N; kwargs...)

Return a vector with set SVector parameters, falling back on default values if necessary.

_assure_scalar(v)

Accept a scalar or a vector of length one and return it as a scalar. Raise assertion error if other objects are passed.

_upgrade_to_svec(v, ::Val{N}) where N

Receive a scalar or a vector of length 1 and return a length N static vector of repeats of entry v.

_upgrade_to_vec(v, N)

Receive a scalar or a vector of length 1 and return a length N vector of repeats of entry v.

accept_reject!(updt, global_ws, ws, step, i=1)

Finish computations of the log-likelihood ratio between the target and proposal in MH acceptance probability and accept/reject respectively.

acceptance_rate!(adpt::AdaptationUnifRW)

Destructive computation of a current acceptance rate that also resets the number of proposals and accepted samples to zeros.

acceptance_rate(adpt::AdaptationUnifRW)

Compute current acceptance rate of the Metropolis-Hastings update step

check_if_execute(callback::SavingCallback, iter)

Return true if the mcmc iteration iter is one at which an intermediate save is to be made.

cleanup!(callback::SavingCallback, ws::GlobalWorkspace, iter)

Save the entire MCMC chain, history of proposals, acceptance history etc.

compute_ll!(
    global_ws::GlobalWorkspace,
    ws::LocalWorkspace,
    step,
)

Evaluate the proposal log-likelihood at the observations.

compute_δ(p, mcmc_iter)

δ decreases roughly proportional to scale/sqrt(iteration)

compute_ϵ(ϵ_old, p, a_r, δ, flip=1.0, f=identity, finv=identity)

ϵ is moved by δ to adapt to target acceptance rate

custom_zero(x::T, ::Type{elT}) where {T,elT}

Create a zero with eltype elT, that is of the same structure as the collection x.

Examples

julia> custom_zero(3.0, Bool)
false
julia> custom_zero([3.0, 4.0], Bool)
2-element Array{Bool,1}:
 0
 0
julia> custom_zero(SVector{2}(1, 2), ComplexF64)
2-element SArray{Tuple{2},Complex{Float64},1,2} with indices SOneTo(2):
 0.0 + 0.0im
 0.0 + 0.0im

data_to_csv(f, ws::GlobalWorkspace, i)

Write data entries to a CSV file.

execute!(sc::SavingCallback, ws::GlobalWorkspace, iter)

Save the chain of accepted states, proposed states and acceptance history to the disk.

find_available_name(path, filename, disambig_num, extension=".csv")

Check if a chosen filename already exists, if so, then tries appending consecutive numbers to the end of the file until the first one that is not used yet is found.

find_starting_idx(callback::SavingCallback, iter)

Find the last index for which saving was done.

init!(
    mcmc::MCMC,
    num_mcmc_steps,
    data,
    θinit,
    exclude_updates=[];
    kwargs...
)

Initialize the schedule and the global workspace of the MCMC sampler for a given set of updates (already saved in mcmc.updates), a total number of MCMC iterations given by num_mcmc_steps, observed dataset data. θinit is the initial value of the main parameter that the MCMC sampling is done for, exclude_updates lists the update indices and the repspective ranges of mcmc iterations from which these updates are supposed to be omitted from and kwargs lists all additional named arguments passed for creating a global workspace.

init!(callback::SavingCallback)

Create a CSV file for writing into.

init_global_workspace(
    ::MCMCBackend,
    num_mcmc_steps,
    updates::Vector{<:MCMCUpdate},
    data,
    θinit::Vector{T};
    kwargs...
) where T

Initialize the <custom>GlobalWorkspace. <custom>MCMCBackend points to which GlobalWorkspace constructors to use, updates is a list of MCMC updates, θinit is the initial guess for the parameter and kwargs are the named arguments passed to run!.

isequal_except(
    ::AdaptationUnifRW{T}, b::AdaptationUnifRW{S}, args...
    ) where{T,S}

Convenience comparison of AdaptationUnifRW instances. Used only for tests. The fields specified by args are excluded from comparison.

log_prior(::Previous, updt::MCMCParamUpdate, ws::LocalWorkspace, i)

Evaluate the log-prior at θ.

log_prior(::Proposal, updt::MCMCParamUpdate, ws::LocalWorkspace, i)

Evaluate the log-prior at θ°.

log_transition_density(
    ::Previous, updt::MCMCParamUpdate, ws::LocalWorkspace, i
)

Evaluate the log-density for a transition θ → θ°.

log_transition_density(
    ::Proposal, updt::MCMCParamUpdate, ws::LocalWorkspace, i
)

Evaluate the log-density for a transition θ° → θ.

logit(x, a=1.0)

Logit function. (Inverse of sigmoid).

readjust!(rw::UniformRandomWalk, adpt::AdaptationUnifRW, mcmc_iter)

Adaptive readjustment of the range for sampling uniforms by the random walker.

register!(adpt::AdaptationUnifRW, accepted::Bool, ::Any)

Register the result of the acceptance decision in the Metropolis-Hastings step.

register_accept_reject_results!(
    accepted::Bool, updt, ws::LocalWorkspace, step, i=1
)

Register the results of accept/reject step relevant to a local workspace.

register_accept_reject_results!(
    accepted::Bool,
    updt,
    global_ws::GlobalWorkspace,
    local_ws::LocalWorkspace,
    step,
    i=1
)

Register the result of accept/reject step.

remove_curly(::Type{K}) where K

Utility function that removes all type-specifiers listed in the curly brackets.

Examples

julia> remove_curly(Array{Float64,1})
Array

reschedule!(
    schedule::MCMCSchedule,
    num_new_updates=0,
    idxes_to_remove=[],
    idxes_to_add=[]
)

Make changes to the schedule (possibly in the midst of iterating through it). Add num_new_updtes-many allowable updates that can be performed at each MCMC step, idxes_to_remove lists all parameter udpates that are to be completely removed from the MCMC sampler, idxes_to_add lists entries that are to be added to schedule.exclude_updates.

set_proposal!(
    updt::MCMCParamUpdate,
    global_ws::GlobalWorkspace,
    ws::LocalWorkspace,
    step
)

The proposal parameter θ° has been sampled by this point. This function propagates it through workspaces and sets the new parameter in proposal law P°

sigmoid(x, a=1.0)

Sigmoid function. (Inverse of logit).

state(ws::GlobalWorkspace, updt::MCMCParamUpdate)

Return a substate of a gloabl state consisting of coordinates that the updt is concerned with.

strip_decorators(updt_and_decor)

Remove all decorators from a list

time_to_update(adpt::AdaptationUnifRW)

Return true if it's the time to update the ϵ parameter of Uniform random walks

transition(schedule::MCMCSchedule, state)

Determine the next state of the MCMCSchedule iterator, by skipping through all updates that are to be excluded, as per schedule.exclude_updates.

update!(
    updt::MCMCParamUpdate,
    global_ws::GlobalWorkspace,
    ws::LocalWorkspace,
    step,
)

General recipe for performing parameter update (doing an update of the main state of the MCMC sampler).

update_workspaces!(
    local_updt::MCMCParamUpdate,
    global_ws::GlobalWorkspace,
    local_ws::LocalWorkspace,
    step,
    prev_ws,
)

Transfer all the information that is needed at the time of starting the MCMC update step from the global (or a previously used local) to the currently used local workspace.