grapes-quantiles-grapes: Extract posterior distribution quantiles from a fitted...

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

Extract posterior distribution quantiles from a fitted evorates model

Description

This operator extracts quantiles from the posterior distributions for particular parameters from an evorates_fit object or param_block array. This can be used to, for example, get posterior medians or credible intervals.

Usage

fit %quantiles% select

fit %q% 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" or "quantiles".

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, integer, or character vector for specifying quantiles. If unsupplied, default quantiles are selected. Default quantiles are are set to the quantiles already stored in fit, if they exist, otherwise they are set to the lower bound of the 95% credible interval, median, and upper bound (i.e., 2.5%, 50%, and 97.5%). If a numeric vector, this will simply be the quantile to extract (i.e., 0.1 would be the 10% quantile). If an integer vector, an integer i will extract the ith default quantile. If a character vector, numbers as taken as percents (i.e., 10% or even 10 would correspond to 0.1). Quantiles greater than 100% or less than 0% are rounded to 100% and 0%, respectively.

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.

This function uses a custom quantiles estimation function that yields the same results as quantile with type = 7. NAs are always ignored when estimating quantiles, unless all samples for a parameter are NA, in which case all quantile estimates will also be NA.

Value

An array of class "param_block" with a param_type of "quantiles". The dimension of these arrays will generally go in the order of quantiles, then parameters, then chains. Any dimensions of length 1 are collapsed and stored as attributes. If fit is a chains param_block array, parameters are automatically renamed "quantiles(<parameter name>)" to help keep track of parameter manipulations.

See Also

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

Examples

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

#extracting directly from evorates fit
cet_fit %quantiles% "R_mu"
#regular expressions
cet_fit %quantiles% "R"
#using . is a quick way to extract ALL parameters!
cet_fit %quantiles% "."
#numeric index-based selection
cet_fit %quantiles% 1
cet_fit %quantiles% -1
#select particular quantiles
#e.g., medians
cet_fit %quantiles% list("R_mu", 0.5)
cet_fit %quantiles% list("R_mu", 2L)
cet_fit %quantiles% list("R_mu", "50%")
#e.g., 95% credible intervals
cet_fit %quantiles% list("R_mu", c(0.025, 0.975))
cet_fit %quantiles% list("R_mu", c(1L, 3L))
cet_fit %quantiles% list("R_mu", c("2.5%", "97.5%"))
#getting sampler parameters
cet_fit %quantiles% "lik__"
#note warmup samples automatically excluded from "lik__" if combined with "R_mu"
cet_fit %quantiles% 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 %quantiles% list("Mesoplodon", 0.5)
#note change in numeric index behavior
par %quantiles% 1

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