remove.trend: Extract detrended branchwise rate parameters from a fitted...
In bstaggmartin/evorates: Evolving Rate Models of Continuous Trait Evolution

remove.trend

R Documentation

Extract detrended branchwise rate parameters from a fitted evorates model

Description

This function extracts "detrended" 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) or has no trend parameter.

Usage

remove.trend(
  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 dtrended 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) parameters, the detrended 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 uncent_Rdev_i's (i.e., an "uncentered rate deviations"), where i is the index of the corresponding edge in fit$call$tree.

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 detrended branchwise rate parameters go by the name uncent_Rdev_i (i.e., an "uncentered rate deviation"), where i is the index of the corresponding edge in fit$call$tree.

Examples

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

#get posterior samples of detrended branchwise rates
uncent.Rdevs <- remove.trend(cet_fit)
#let's say we want to get detrended rates for some of the edges towards the root
plot(cet_fit$call$tree); edgelabels()
#select particular edges
uncent.Rdevs <- remove.trend(cet_fit, select = c(1, 2, 9, 28, 29, 30))
#maybe specific samples too?
uncent.Rdevs <- remove.trend(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 detrended rates in the genus Mesoplodon
edges <- get.clade.edges(cet_fit$call$tree, "Mesoplodon")
Meso.uncent.Rdevs <- remove.trend(cet_fit, select = edges)
#or at everything EXCEPT Mesoplodon
notMeso.uncent.Rdevs <- remove.trend(cet_fit, select = -edges)

#could also look at quantiles, means, or diagnostics
med.uncent.Rdevs <- remove.trend(cet_fit, select = edges,
                                 type = "quantiles",
                                 extra.select = 0.5)
mean.uncent.Rdevs <- remove.trend(cet_fit, select = edges,
                                  type = "means")
init.uncent.Rdevs <- remove.trend(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.uncent.Rdevs <- remove.trend(cet_fit, select = edges,
                                 type = "quantiles",
                                 extra.select = 0.5,
                                 simplify = FALSE)
                 
#note that all this equivalent to detrending <fit> %<type>% list(<select>, <extra.select>)
#at least when <fit> includes branchwise rate parameters

bstaggmartin/evorates documentation built on May 31, 2024, 5:56 a.m.