remove.trend: Extract detrended branchwise rate parameters from a fitted...

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

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.

See Also

more information on detrending is available in the documentation for fit.evorates, input.evorates, run.evorates, and output.evorates, particularly in the section on parameter definitions

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

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/backwards-BM-simulator documentation built on June 3, 2024, 5:51 p.m.