Samplers

ABC(params::ElementOrVector{Symbol},
scale::ElementOrVector{T}, summary::Function,
epsilon::Real; kernel::KernelDensityType=SymUniform,
dist::Function=(Tsim, Tobs) -> sqrt(sum(abs2, Tsim - Tobs)),
proposal::SymDistributionType=Normal, maxdraw::Integer=1,
nsim::Integer=1, decay::Real=1.0, randeps::Bool=false,
args...)

Construct a `Sampler` object for ABC sampling. Parameters are assumed to be continuous, but may be constrained or unconstrained.
Returns a `Sampler{ABCTune}` type object.
* `params`: stochastic node(s) to be updated with the sampler.  Constrained parameters are mapped to unconstrained space according to transformations defined by the Stochastic `unlist()` function.
* `scale` : scaling value or vector of the same length as the combined elements of nodes `params` for the `proposal` distribution.  Values are relative to the unconstrained parameter space, where candidate draws are generated.
* `summary` : function that takes a vector of observed or simulated data and returns a summary statistic or vector of statistics.
* `epsilon` : target tolerance for determining how similar observed and simulated data summary statistics need to be in order to accept a candidate draw.
* `kernel` : weighting kernel density of type `Biweight`, `Cosine`, `Epanechnikov`, `Normal`, `SymTriangularDist`, `SymUniform`, or `Triweight` to use in measuring similarity between observed and simulated data summary statistics.  Specified `epsilon` determines the standard deviation of Normal kernels and widths of the others.
* `dist` : positive function for the kernel density to compute distance between vectors of observed (`Tobs`) and simulated (`Tsim`) data summary statistics (default: Euclidean distance).
* `proposal` : symmetric distribution of type `Biweight`, `Cosine`, `Epanechnikov`, `Normal`, `SymTriangularDist`, `SymUniform`, or `Triweight` to be centered around current parameter values and used to generate proposal draws.  Specified `scale` determines the standard deviations of Normal proposals and widths of the others.
* `maxdraw` : maximum number of unaccepted candidates to draw in each call of the sampler.  Draws are generated until one is accepted or the maximum is reached.  Larger values increase acceptance rates at the expense of longer runtimes.
* `nsim` : number of data sets to simulate in deciding whether to accept a candidate draw.  Larger values lead to closer approximations of the target distribution at the expense of longer runtimes.
* `decay` : if `0 < decay <= 1`, the rate at which internal tolerances are monotonically decreased from the initial distance between observed and simulated summary statistics toward the maximum of each subsequent distance and `epsilon`; if `decay = 0`, internal tolerances are fixed at `epsilon`.
* `randeps` : whether to perturb internal tolerances by random exponential variates.
* `args...` : additional keyword arguments to be passed to the `dist` function.

ABC(params::ElementOrVector{Symbol},
scale::ElementOrVector{T}, summary::Function,
epsilon::Real, proposal::Function; kernel::KernelDensityType=SymUniform,
dist::Function=(Tsim, Tobs) -> sqrt(sum(abs2, Tsim - Tobs)),
maxdraw::Integer=1,
nsim::Integer=1, decay::Real=1.0, randeps::Bool=false,
args...)

Construct a `Sampler` object for ABC sampling. Parameters are assumed to be continuous, but may be constrained or unconstrained.
Returns a `Sampler{ABCTune}` type object.
* `params`: stochastic node(s) to be updated with the sampler.  Constrained parameters are mapped to unconstrained space according to transformations defined by the Stochastic `unlist()` function.
* `summary` : function that takes a vector of observed or simulated data and returns a summary statistic or vector of statistics.
* `epsilon` : target tolerance for determining how similar observed and simulated data summary statistics need to be in order to accept a candidate draw.
* `proposal` : a proposal function which proposes a new value. 
* `kernel` : weighting kernel density of type `Biweight`, `Cosine`, `Epanechnikov`, `Normal`, `SymTriangularDist`, `SymUniform`, or `Triweight` to use in measuring similarity between observed and simulated data summary statistics.  Specified `epsilon` determines the standard deviation of Normal kernels and widths of the others.
* `dist` : positive function for the kernel density to compute distance between vectors of observed (`Tobs`) and simulated (`Tsim`) data summary statistics (default: Euclidean distance).
* `maxdraw` : maximum number of unaccepted candidates to draw in each call of the sampler.  Draws are generated until one is accepted or the maximum is reached.  Larger values increase acceptance rates at the expense of longer runtimes.
* `nsim` : number of data sets to simulate in deciding whether to accept a candidate draw.  Larger values lead to closer approximations of the target distribution at the expense of longer runtimes.
* `decay` : if `0 < decay <= 1`, the rate at which internal tolerances are monotonically decreased from the initial distance between observed and simulated summary statistics toward the maximum of each subsequent distance and `epsilon`; if `decay = 0`, internal tolerances are fixed at `epsilon`.
* `randeps` : whether to perturb internal tolerances by random exponential variates.
* `args...` : additional keyword arguments to be passed to the `dist` function.

function Empirical(params::Symbol, width::Int64; replace::Bool=false)

This Sampler generates Samples from a distribution by selecting a random value from this distribution. The move will always be accepted. Sampling can be done with or without replacement.

HMC(params::ElementOrVector{Symbol}, epsilon::Real, L::Integer; args...)

Construct a Sampler object for HMC sampling. Parameters are assumed to be continuous, but may be constrained or unconstrained.

Returns a Sampler{HMCTune} type object.

• params: stochastic node(s) to be updated with the sampler. Constrained parameters are mapped to unconstrained space according to transformations defined by the Stochastic unlist() function.

• epsilon: step size.

• L: number of steps to take in the Leapfrog algorithm.

• Sigma: covariance matrix for the multivariate normal proposal distribution. The covariance matrix is relative to the unconstrained parameter space, where candidate draws are generated. If omitted, the identity matrix is assumed.

MISS(params::ElementOrVector{Symbol})

Construct a Sampler object to sampling missing output values. The constructor should only be used to sample stochastic nodes upon which no other stochastic node depends. So-called ‘output nodes’ can be identified with the keys() function. Moreover, when the MISS constructor is included in a vector of Sampler objects to define a sampling scheme, it should be positioned at the beginning of the vector. This ensures that missing output values are updated before any other samplers are executed.

Returns a Sampler{Dict{Symbol, MISSTune}} type object.

• params: stochastic node(s) that contain missing values (NaN) to be updated with the sampler.

NUTS(params::ElementOrVector{Symbol}, classic_nuts; epsilon::Real = -Inf, kwargs...)

Construct a Sampler object for NUTS sampling, with the algorithm´s step size parameter adaptively tuned during burn-in iterations. Parameters are assumed to be continuous, but may be constrained or unconstrained. The variant parameter controls whether the Riemannian variant of the NUTS algorithm (https://arxiv.org/abs/1304.1920) or the classical variant (https://jmlr.org/papers/v15/hoffman14a.html) is used.

Returns a Sampler{NUTSTune} type object.

• params: stochastic node(s) to be updated with the sampler. Constrained parameters are mapped to unconstrained space according to transformations defined by the Stochastic unlist() function.

• variant of the NUTS sampler. Options are

  • classic_nuts : classic version (default)
  • riemann_nuts : Riemannian version.

• epsilon: step size which can be presupplied. If the standard (-Inf) is chosen, it will be automatically adapted

PNUTS(params::ElementOrVector{Symbol}; args...)

Construct a Sampler object for PNUTS sampling. The Parameter is assumed to be a tree.

Returns a Sampler{PNUTSTune} type object.

• params: stochastic node to be updated with the sampler.

• args...: additional keyword arguments to be passed to the PNUTSVariate constructor.

PPHMC(params::ElementOrVector{Symbol}; args...)

Construct a Sampler object for PPHMC sampling. The Parameter is assumed to be a tree.

Returns a Sampler{PPHMCTune} type object.

• params: stochastic node to be updated with the sampler.

• args...: additional keyword arguments to be passed to the PNUTSVariate constructor.

RWM(params::ElementOrVector{Symbol},
              scale::ElementOrVector{T}; args...) where {T<:Real})

Construct a Sampler object for RWM sampling. Parameters are assumed to be continuous, but may be constrained or unconstrained.

Returns a Sampler{RWMTune} type object.

• params: stochastic node(s) to be updated with the sampler. Constrained parameters are mapped to unconstrained space according to transformations defined by the Stochastic unlist() function.

• scale: scaling value or vector of the same length as the combined elements of nodes params for the proposal distribution. Values are relative to the unconstrained parameter space, where candidate draws are generated.

• args...: additional keyword arguments to be passed to the RWMVariate constructor.

RWM(params::ElementOrVector{Symbol}, moves::Array{Symbol}; args...)

Construct the RWM sampler for Trees. If you set moves to :all it will use all eligible moves to change the tree. These are currently: NNI, SPR, Slide, Swing, :EdgeLength

Returns a Sampler{RWMTune} type object.

Slice(params::ElementOrVector{Symbol},
            width::ElementOrVector{T},
            ::Type{F}=Multivariate;
            transform::Bool=false) where {T<:Real, F<:SliceForm}

Construct a Sampler object for Slice sampling. Parameters are assumed to be continuous, but may be constrained or unconstrained.

Returns a Sampler{SliceTune{Univariate}} or Sampler{SliceTune{Multivariate}} type object if sampling univariately or multivariately, respectively.

• params: stochastic node(s) to be updated with the sampler.

• width: scaling value or vector of the same length as the combined elements of nodes params, defining initial widths of a hyperrectangle from which to simulate values.

• F : sampler type. Options are

  • :Univariate : sequential univariate sampling of parameters.
  • :Multivariate : joint multivariate sampling.

• transform: whether to sample parameters on the link-transformed scale (unconstrained parameter space). If true, then constrained parameters are mapped to unconstrained space according to transformations defined by the Stochastic unlist() function, and width is interpreted as being relative to the unconstrained parameter space. Otherwise, sampling is relative to the untransformed space.

SliceSimplex(params::ElementOrVector{Symbol}; args...)

Construct a Sampler object for which SliceSimplex sampling is to be applied separately to each of the supplied parameters. Parameters are assumed to be continuous and constrained to a simplex.

Returns a Sampler{SliceSimplexTune} type object.

• params: stochastic node(s) to be updated with the sampler.

• args...: additional keyword arguments to be passed to the SliceSimplexVariate constructor.