Samplers
Functions found in all files of samplers folder, ordered according to file of origin.
ABC
MCPhylo.ABC
— FunctionABC(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.
Empirical
MCPhylo.Empirical
— Functionfunction 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
MCPhylo.HMC
— FunctionHMC(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 Stochasticunlist()
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
MCPhylo.MISS
— FunctionMISS(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
MCPhylo.NUTS
— FunctionNUTS(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 Stochasticunlist()
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
P-NUTS
MCPhylo.PNUTS
— FunctionPNUTS(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
MCPhylo.PPHMC
— FunctionPPHMC(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
MCPhylo.RWM
— FunctionRWM(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 Stochasticunlist()
function.scale
: scaling value or vector of the same length as the combined elements of nodesparams
for theproposal
distribution. Values are relative to the unconstrained parameter space, where candidate draws are generated.args...
: additional keyword arguments to be passed to theRWMVariate
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
MCPhylo.Slice
— FunctionSlice(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 nodesparams
, 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). Iftrue
, then constrained parameters are mapped to unconstrained space according to transformations defined by the Stochasticunlist()
function, andwidth
is interpreted as being relative to the unconstrained parameter space. Otherwise, sampling is relative to the untransformed space.
SliceSimplex
MCPhylo.SliceSimplex
— FunctionSliceSimplex(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 theSliceSimplexVariate
constructor.