get.R: Extract branchwise rate parameters from a fitted evorates...

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

Extract branchwise rate parameters from a fitted evorates model

Description

This is a convenient function for extracting branchwise rate parameters from an evorates_fit object. It even works when the object has no branchwise rate parameters (i.e., a Brownian Motion model).

Usage

get.R(
  fit,
  select = seq_len(Nedge(fit)),
  type = c("chains", "quantiles", "means", "diagnostics"),
  extra.select = NULL,
  simplify = TRUE
)

Arguments

fit	An object of class "evorates_fit".
select	A numeric vector specifying edge indices in fit$call$tree for which to extract branchwise rate parameters. These can be negative to exclude edges as well. All edges indices are extracted by default.
type	A string specifying whether to extract posterior samples ("chains"), quantiles ("quantiles"), means ("means"), or diagnostics ("diagnostics"). Can be any unambiguous abbreviation of these strings as well. Defaults to extracting posterior samples.
extra.select	A numeric, integer, or character vector specifying the specific samples/ quantiles/diagnostics to extract, depending on type. Defaults to NULL, which generally extracts all available samples/quantiles/diagnostics. See documentation on param_block operators for details (grapes-chains-grapes, grapes-quantiles-grapes, grapes-means-grapes, or grapes-diagnostics-grapes).
simplify	TRUE or FALSE: should the resulting param_block array be simplified? If TRUE (the default), dimensions of length 1 in the result are automatically collapsed, with corresponding information stored as attributes (this is the default behavior of param_block operators).

Details

The edge indices of fit$call$tree can be viewed by running: plot(fit$call$tree); edgelabels().

In the case of a fit with constrained rate variance (R_sig2) and trend (R_mu) parameters, fit doesn't contain explicit branchwise rate parameters ( R_i, where i is the index of the corresponding edge). In this case, a simple Brownian Motion model of trait evolution has been fitted, and the branchwise rate parameters are all equivalent to the rate at the root (R_0). As such, this function just creates a param_block array of R_0 replicated the appropriate number of times, with parameters renamed with the appropriate R_i's.

Value

An array of class "param_block" with a param_type set to whatever type is. The dimension of these arrays will generally go in the order of iterations/quantiles/diagnostics, then parameters, then chains. Any dimensions of length 1 are collapsed and stored as attributes if simplify is TRUE. Note that branchwise rate parameters go by the name R_i, where i is the index of the corresponding edge in fit$call$tree.

See Also

Other parameter extraction functions: get.bg.rate(), get.post.traits(), remove.trend()

Examples

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

#get posterior samples of branchwise rates
Rs <- get.R(cet_fit)
#let's say we want to get some of the edges towards the root
plot(cet_fit$call$tree); edgelabels()
#select particular edges
Rs <- get.R(cet_fit, select = c(1, 2, 9, 28, 29, 30))
#maybe specific samples too?
Rs <- get.R(cet_fit, select = c(1, 2, 9, 28, 29, 30),
            extra.select=c(1, 23, 47))

#this may be a more common way to get edge indices; say we want to look at the genus Mesoplodon
edges <- get.clade.edges(cet_fit$call$tree, "Mesoplodon")
Meso.Rs <- get.R(cet_fit, select = edges)
#or at everything EXCEPT Mesoplodon
notMeso.Rs <- get.R(cet_fit, select = -edges)

#could also look at quantiles, means, or diagnostics
med.Rs <- get.R(cet_fit, select = edges,
                type = "quantiles",
                extra.select = 0.5)
mean.Rs <- get.R(cet_fit, select = edges,
                 type = "means")
init.Rs <- get.R(cet_fit, select = edges,
                 type = "diagnostics",
                 extra.select = c("inits", "ess"))
                 
#here's an example of what happens when you don't simplify the result
med.Rs <- get.R(cet_fit, select = edges,
                type = "quantiles",
                extra.select = 0.5,
                simplify = FALSE)
                 
#note that all this is equivalent to running <fit> %<type>% list(<select>, <extra.select>)
#at least when <fit> includes branchwise rate parameters

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