grapes-chains-grapes: Extract posterior distribution samples from a fitted evorates...

In bstaggmartin/backwards-BM-simulator: Evolving Rate Models of Continuous Trait Evolution

Extract posterior distribution samples from a fitted evorates model

Description

This operator extracts samples from the posterior distributions (i.e., iterations from the chains) for particular parameters from an evorates_fit object or param_block array.

Usage

fit %chains% select

fit %c% select

Arguments

fit

An object of class "evorates_fit" or "param_block". If fit is a param_block array, it must have a param_type of "chains".

select

A list with two elements (2nd element is optional): A character or numeric vector for selecting parameters. If a character vector, entries are matched to parameter names using regular expressions, with one key exception: if any entries are exact matches to sampling parameter names, these will be used to select parameters from the sampler.params element of fit instead, if it exists (see details). If a numeric vector, entries are matched to edge indices to select branchwise rate parameters; these can be negative to instead exclude branchwise rates. If no branchwise rate parameters are found, a number i will instead select the ith parameter in fit. A numeric vector for selecting samples from the distribution (i.e., iterations from the chains). If unsupplied, all samples are selected.

Details

In the case that a numeric vector is provided to select parameters and no parameters with names following the pattern "R_i" are found, the function then looks for the pattern "Rdev_i", then "uncent_Rdev_i". If neither of these are found, then it finally defaults to selecting the ith parameters. If a single parameter name involves multiple "R_i" patterns, the first pattern is always used (e.g., R_1%-%R_2 would correspond to 1). Similarly, if multiple parameters match to a single number, the first parameter is always used (similar to behavior of match).

The sampler.params element of fit always includes 9 parameters, named: "accept_stat__", "treedepth__", "stepsize__", "divergent__", "n_leapfrog__", "energy__", "prior__", "lik__", and "post__". This tends to include both warmup and non-warmup samples, but warmup samples are automatically excluded if both sampler parameters and normal parameters are selected by this function. Most of these parameters are rather technical quantities used to tune the Hamiltonian Monte Carlo sampler run by Stan (see Stan manual for further details on what they mean). Generally, users will only want to look at the last 3 parameters, which give the (log) prior probability, likelihood, and posterior probability, respectively, of sampled parameters. Note that these are on the sampling scale and will differ from those for the originally-scaled data by a constant. Also, the posterior probability will be affected by what lik.power was set to for fitting the model. In some cases, users may also wish to look at what parameter values are associated with divergent transitions (i.e., iterations where divergent__ = 1), which indicate regions of parameter space where the sampler got "stuck", yielding potentially misleading posterior distribution estimates.

Value

An array of class "param_block" with a param_type of "chains". The dimension of these arrays will generally go in the order of iterations, then parameters, then chains. Any dimensions of length 1 are collapsed and stored as attributes.

See Also

Other param_block operators: %diagnostics%(), %means%(), %quantiles%(), %select%()

Examples

#get whale/dolphin evorates fit
data("cet_fit")

#extracting directly from evorates fit
cet_fit %chains% "R_mu"
#regular expressions
cet_fit %chains% "R"
#using . is a quick way to extract ALL parameters!
cet_fit %chains% "."
#numeric index-based selection
cet_fit %chains% 1
cet_fit %chains% -1
#select particular samples
cet_fit %chains% list("R_mu", 1)
#getting sampler parameters
cet_fit %chains% "lik__"
#note warmup samples automatically excluded from "lik__" if combined with "R_mu"
cet_fit %chains% c("R_mu", "lik__")

#extracting from a param_block array
par <- get.bg.rate(fit = cet_fit,
                   node.groups = setNames(list('Mesoplodon','Orcinus',c('Pseudorca','Feresa')),
                                          c('Mesoplodon','Orca','Globicephalinae')),
                   )
par %chains% list("Mesoplodon", 36)
#note change in numeric index behavior
par %chains% 1

bstaggmartin/backwards-BM-simulator documentation built on June 3, 2024, 5:51 p.m.