Branch-Level Inference Framework for Recognizing Optimal Shifts in Traits

Methods for detecting, visualizing, and evaluating cladogenic shifts in multivariate trait data on phylogenies. Implements penalized-likelihood multivariate generalized least squares models and a greedy step-wise shift search for high-dimensional trait datasets and large trees via searchOptimalConfiguration(). Provides tools for inspecting search trajectories, summarizing branch and lineage rates, analyzing shift timing and magnitudes, estimating post-hoc regime covariance and integration, and running simulation-based calibration and tuning. The search follows approaches developed in Smith et al. (2023) and Berv et al. (2024) . Methods build on multivariate generalized least squares approaches described in Clavel et al. (2019) and implemented in the mvgls() function from the 'mvMORPH' package. Documentation and worked examples are available at < https://jakeberv.com/bifrost/>.

bifrost

bifrost performs branch-level inference of multi-regime, multivariate trait evolution on a phylogeny using penalized-likelihood multivariate GLS fits. The current version searches for evolutionary model shifts under a multi-rate Brownian Motion (BMM) model with proportional regime VCV scaling, operates directly in trait space (for example, without PCA), and is designed for high-dimensional datasets (p > n) and large trees (> 1000 tips).

The method works with fossil tip-dated trees and with a wide range of multivariate comparative data, including GPA-aligned morphometric coordinates, linear dimensions, and related trait matrices. A future major release will add support for the multivariate scalar Ornstein-Uhlenbeck process.

CRAN downloads

Installation

CRAN release (0.2.0)

install.packages("bifrost")

GitHub development source

# install.packages("remotes")
remotes::install_github("jakeberv/bifrost")

Windows users:
Install Rtools for your R version and ensure that it is added to your system PATH.

macOS users:
You may need to install XQuartz to build or run packages that depend on certain graphical or system libraries.

Source archives

GitHub source ZIP and tar.gz downloads include the package code, help files, and tests, together with licensing and project metadata. Website articles, notebooks, empirical example data, and development tools are excluded from these downloads. Those materials remain available in repository clones and through the package website and example-data guide. These archive exclusions also apply when Zenodo captures a GitHub release.

Development status

Version 0.2.2 is being prepared for release on GitHub; the latest published GitHub release is 0.2.1 and CRAN currently distributes 0.2.0. All require R 4.2 or newer. The 0.2.2 update makes search initialization explicit and corrects progress-related random-stream and numerical-thread handling, with console-display refinements. These changes can affect results relative to earlier releases; see the initialization and reproducibility notes in NEWS. See the development-status page for current CRAN and GitHub availability, release caveats, and the website article policy. See NEWS for the complete changelog.

Example data

The empirical case studies use download-on-demand example data rather than packaged datasets. Package installation and core analyses remain offline; data are fetched only by explicit calls to bifrost_example_file(). The first call without a verified cache downloads and validates the manifest currently tracked on GitHub main, then verifies the selected artifact against the manifest's SHA-256 checksum and byte size. Later calls reuse the verified cache, while refresh = TRUE checks main again for maintained updates. The supported identifiers and their provenance are listed in the example-data guide.

tree_path <- bifrost_example_file("jaw-tree")
landmark_path <- bifrost_example_file("jaw-landmarks")
fish.tree <- readRDS(tree_path)
landmarks <- readRDS(landmark_path)

Overview

• Primary goal. Infer where, when, and how patterns of phenotypic evolution change across a tree using many traits simultaneously.
• Model. Multi-rate Brownian Motion with regime-specific VCVs estimated via penalized-likelihood (mvMORPH::mvgls), supporting p >= n.
• Search. Greedy, step-wise acceptance of shifts guided by information criteria (GIC or BIC), with optional per-shift IC weights.
• Scale. Parallel candidate scoring using the future ecosystem; practical on thousands of taxa x traits.

Key features

• Joint multivariate modeling without information loss or distortion due to PCA.
• Under BMM, proportional VCV scaling across regimes for tractability at high p.
• Provides a multivariate phylogenetic GLS (mvPGLS)-like framework in which hidden branch-specific rate regimes are inferred and incorporated when estimating predictor effects.
• Candidate shift nodes are determined by a minimum clade size specified by the user.
• Output includes estimated VCV per regime, shift weights, and SIMMAP-style mappings for downstream visualization and analysis.

Documentation

The complete worked articles are maintained on the package website. Their sources and generated artifacts are intentionally excluded from the CRAN source package, so installing bifrost does not install vignettes or their empirical payloads.

Background and theory

• Brownian Motion and Multivariate Shifts
  Conceptual background on Brownian motion, multivariate covariance, and what branch-specific shifts mean in bifrost.
• Whole-Tree Models, PCA, and bifrost
  Explains why whole-tree homogeneous models and PCA truncation can mislead inference when evolutionary processes vary across the tree.

Getting Started

• Quick Start with bifrost
  A practical introduction to the core bifrost workflow using a minimal simulated example, including setup, key arguments, outputs, and interpretation.
• Detecting Evolutionary Shifts in Paleozoic Fish Jaw Shape with bifrost
  A full empirical case study using download-on-demand fossil jaw-shape example data, showing how to run, inspect, and interpret a real bifrost analysis end to end.

Rate Mapping

• Mapping Sensitivity in Jaw-Shape Evolutionary Rates with rateMap, Part 1 A follow-up case study showing the compute-first rateMap() workflow: build a reusable branch-rate summary object from completed searches, diagnose broad fitted-rate ranges, and display near-zero branches with explicit diagnostic metadata.
• Mapping Sensitivity in Jaw-Shape Evolutionary Rates with rateMap, Part 2 Extends the same jaw-shape sweep into IC weighting, uncertainty summaries, same-topology tree samples, original-scale rates, interval maps, and additional diagnostics.

Avian Skeleton Case Study

• Passerine Body Plan Evolution, Part 1: Fitting and Inspecting a Search Introduces the empirical dataset, fits the manuscript-scale search, and inspects the inferred shifts and IC trajectory.
• Passerine Body Plan Evolution, Part 2: Lineage-Rate Summaries Reconstructs tip-level lineage-rate summaries and visualizes their temporal and spatial variation.
• Passerine Body Plan Evolution, Part 3: Shift Timing and Distribution Fits Extracts shift events and evaluates waiting-time and lineage-rate distributions.
• Passerine Body Plan Evolution, Part 4: Shift Magnitude Comparisons Quantifies and compares the magnitudes of inferred rate shifts among biological groups.
• Passerine Body Plan Evolution, Part 5: Post-hoc Integration and Covariance Structure Examines regime-specific covariance, modularity, integration, and post-hoc phylogenetic relationships.

Simulation and Calibration

• Empirically Calibrated Simulations for bifrost, Part 1: Performance Builds reproducible null and shifted simulations and reports false-positive behavior and strict and fuzzy shift recovery.
• Empirically Calibrated Simulations for bifrost, Part 2: Tuning and Application Tunes search controls with null safeguards and fuzzy balanced accuracy, then carries the selected settings into empirical analysis.

Additional note

Though bifrost was initially developed as a framework for inferring macroevolutionary regime shifts in multivariate trait data, it can also be applied to perform multivariate phylogenetic generalized least squares (pGLS) analyses with factors or continuous predictors (e.g., cbind(trait1, trait2, ...) ~ predictor, or "trait_data[, 1:5] ~ trait_data[, 6]" when working directly with a matrix). In this context, bifrost identifies branch-specific rate variation under a multi-rate Brownian Motion model and fits the pGLS conditional on the resulting residual (phylogenetic) covariance structure, so estimated effect sizes and uncertainties account for "hidden" rate variation not explained by the predictors. This is conceptually similar to hidden-state approaches (e.g., Boyko et al. 2023), except that here the regimes influence variance and evolutionary rate rather than introducing regime-specific means. This use case is an active area of ongoing methodological development.

Citation

If you use bifrost, please cite the package paper first listed below and the other references as appropriate. Because bifrost relies on mvMORPH and its penalized-likelihood framework, please also cite the mvMORPH references below. The same set is also available from:

citation("bifrost")

Software releases are archived on Zenodo under the concept DOI 10.5281/zenodo.23268805, which covers all archived versions of bifrost.

Recommended citations

1. bifrost methods / package paper
   Berv JS, Fox N, Thorstensen MJ, Lloyd-Laney H, Troyer EM, Rivero-Vega RA, Smith SA, Friedman M, Fouhey DF, Weeks BC (2026). bifrost: an R package for scalable inference of phylogenetic shifts in multivariate evolutionary dynamics. Methods in Ecology and Evolution. In press. Preprint on bioRxiv.

2. bifrost application paper
   Berv JS, Probst CM, Claramunt S, Shipley JR, Friedman M, Smith SA, Fouhey DF, Weeks BC (2026). Rates of passerine body plan evolution in time and space. Nature Ecology & Evolution, 10, 1559–1573. https://doi.org/10.1038/s41559-026-03110-5

3. mvMORPH package paper
   Clavel J, Escarguel G, Merceron G (2015). mvmorph: an R package for fitting multivariate evolutionary models to morphometric data. Methods in Ecology and Evolution, 6(11), 1311-1319. https://doi.org/10.1111/2041-210X.12420

4. Penalized-likelihood framework paper
   Clavel J, Aristide L, Morlon H (2019). A Penalized Likelihood Framework for High-Dimensional Phylogenetic Comparative Methods and an Application to New-World Monkeys Brain Evolution. Systematic Biology, 68(1), 93-116. https://doi.org/10.1093/sysbio/syy045

Contributing

Bug reports, feature requests, and pull requests are welcome. Please open an issue at https://github.com/jakeberv/bifrost/issues.

License

This project is released under the GPL (>= 2) License. See the LICENSE file for details.

Acknowledgements and dependencies

bifrost builds on substantial work from mvMORPH, phytools, ape, future, and future.apply. The greedy search algorithm is adapted from Mitov et al. 2019 and Smith et al. 2023. See the DESCRIPTION file for complete dependency and version information.

The name of our R package is inspired by the Bifröst, the rainbow bridge of Norse mythology that connects Earth (Midgard) and Asgard within the cosmic structure of Yggdrasil, the Tree of Life, echoing how this framework links observable data to hidden evolutionary shifts across the history of life.

Development of the bifrost R package was supported by the Oxford Research Software Engineering Group, with support from Schmidt Sciences, LLC. and the Michigan Institute for Data Science and AI in Society.