Run a brms regression model across a population of phylogenetic trees

phylogenetic_uncertainty runs a brms regression model across a population of phylogenetic trees.

phylogenetic_uncertainty(formula, data, phylos, sp.id.column, cores = 1,
iter = 5000, fit.name, thin = 0, save.fits = FALSE,
save.combined = FALSE, path = "./", pb = TRUE, ...)

Arguments

formula: A model formula. It must not include the random effect term referring to the phylogeny.
data: A data frame containing the data to be used in the model.
phylos: An object of class 'multiPhylo' (see multiphylo).
sp.id.column: The name of the column containing the 'taxa' label (i.e. the labels that match those in the tree tips).
cores: Number of cores to use for parallelization. Default is 1 (no parallelization).
iter: Integer with the number of the iterations as in brm.
fit.name: Character string with the name of a RDS file to be saved.
thin: Integer with the thinning rate as in brm.
save.fits: Logical to control if single fits are saved as RDS files. Default is FALSE. If 'save.combined' is also FALSE then the model fit is returned into the R environment.
save.combined: Logical to control if the combined single fit is saved as a RDS file. Default is FALSE. If 'save.fits' is also FALSE then the model fit is returned into the R environment.
path: Character string with the directory path in which to save model fit(s) (when either 'save.combined' or 'save.fits' are TRUE). The current working directory is used as default.
pb: Logical to control if a progress bar is used. Default is TRUE.
...: Additional arguments to be passed to brm for further customizing models.

Value

The function returns a fit model that combines all submodels with individual phylogenies. Individual submodels can be saved if save.fits = TRUE.

Details

The function allows to take into account phylogenetic uncertainty when running phylogenetically informed regressions by running several models with a population of trees (ideally the highest posterior trees). Individual models are then combined into a single model fit.

References

Araya-Salas (2022), brmsish: miscellaneous functions to customize brms bayesian regression models. R package version 1.0.0.Paul-Christian Buerkner (2017). brms: An R Package for Bayesian Multilevel Models Using Stan. Journal of Statistical Software, 80(1), 1-28. doi:10.18637/jss.v080.i01

Author

Marcelo Araya-Salas marcelo.araya@ucr.ac.cr)

Examples

if (FALSE) { # \dontrun{
# example taken from https://cran.r-project.org/web/packages/brms/vignettes/brms_phylogenetics.html
phylo <- ape::read.nexus("https://paul-buerkner.github.io/data/phylo.nex")

# quick and dirty trick to make the phylo multiphylo by replicating it
phylos <- list(phylo, phylo)
class(phylos) <- "multiPhylo"

data_simple <- read.table("https://paul-buerkner.github.io/data/data_simple.txt",
header = TRUE)

# run model
pu_mod <- phylogenetic_uncertainty(phen ~ cofactor,
data = data_simple, sp.id.column = "phylo",
phylos = phylos,
 iter = 3000, save.fits = FALSE,
 save.combined = FALSE, chains = 1,
 prior = c(
 prior(normal(0, 10), "b"),
 prior(normal(0, 50), "Intercept"),
 prior(student_t(3, 0, 20), "sd"),
 prior(student_t(3, 0, 20), "sigma"))
 )
} # }