Skip to contents

Release Status

Source: vignettes/articles/development-status.Rmd
development-status.Rmd

This page describes bifrost 0.2.2, published on CRAN and GitHub on October 17, 2026, and the relationship between package source archives and the fuller documentation maintained in the repository.

At a glance

Distribution Version Installation Best for
CRAN 0.2.2 install.packages("bifrost") Current published CRAN release
GitHub, published release 0.2.2 remotes::install_github("jakeberv/bifrost@v0.2.2") Explicit initialization and reproducibility corrections
GitHub, development source Version on main remotes::install_github("jakeberv/bifrost") Latest merged development source

Versions 0.2.0, 0.2.1, and 0.2.2 require R 4.2 or newer. Version 0.2.2 is available on both CRAN and GitHub. CRAN and GitHub releases are published separately.

What 0.2.2 adds

Version 0.2.2 introduces an explicit initialization policy, defaulting to start_strategy = "legacy_1.2.1" for the data-dependent BM/BMM starting values used in the cached vignettes. These starts are supplied to the installed mvMORPH; the dependency itself is neither pinned nor modified. Use start_strategy = "native" for mvMORPH’s own initialization, including EmpBayes. Explicit start values and grid.search = FALSE take precedence. The compatibility policy retains the historical initializer’s limitations; it does not guarantee a globally optimal fit.

The update also corrects progress-related random-stream and numerical-thread handling so enabling progress does not change the fitting random sequence for the same seed and search settings. Results record initialization provenance, and console progress and IC-history displays are refined. Reproducing a cached threshold sweep still requires its original random state, not just the seed of an independently started threshold run. See NEWS and the jaw-shape worked example for details.

What 0.2.1 adds

Version 0.2.1 updates the package’s primary citation to the accepted, in-press paper in Methods in Ecology and Evolution and adds CITATION.cff metadata for GitHub and Zenodo. It also aligns GitHub source archives more closely with the CRAN package by excluding website articles, separately distributed empirical data, and development tooling. Package functions and computational defaults are unchanged from 0.2.0.

What 0.2.0 adds

Version 0.2.0 extends 0.1.4 in several related areas:

  • Search inspection and diagnostics. icTrajectory() and its plot() method expose search histories, while richer stored candidate records retain accepted, rejected, and errored fits. The former plot_ic_acceptance_matrix() wrapper has been removed; use plot(icTrajectory(x)) for a search object. Callers with a raw legacy IC matrix should follow the wrapping and argument-mapping example in NEWS.
  • Branch-rate summaries. rateMap() and its supporting view, control, flagging, print, and plot methods summarize branch-rate patterns across completed searches.
  • Lineage rates and shift distributions. lineage_rates() and related tools summarize inherited lineage rates, shift timing and waiting times, rate distributions, and shift magnitudes.
  • Regime covariance and integration. Post-hoc tools estimate and summarize regime-specific covariance structure, diagnose modules and correlation-space variation, compare integration relationships, and support pGLS analyses.
  • Simulation and tuning. Reproducible null and shifted simulations support strict and fuzzy recovery assessment, fixed-IC tuning grids, null safeguards, and tuning selection by fuzzy balanced accuracy.
  • Formula-based searches. Searches accept formula objects or character strings, response-only numeric data frames for intercept-only analyses, and named-column formulas such as cbind(y1, y2) ~ size + grp.
  • BIC fitting default. When IC = "BIC" and method is omitted, the search uses method = "LL"; explicitly supplied methods still take precedence.
  • Expanded worked documentation. The website includes rate-mapping, five-part avian skeleton, and two-part simulation and calibration workflows, together with downloadable PDFs and executable Colab notebooks.
  • On-demand example data. bifrost_example_file() retrieves supported empirical case-study artifacts only when explicitly requested, verifies them against published checksums, and reuses a local cache. On the first uncached request it downloads and validates the manifest currently tracked on GitHub main, then verifies the selected artifact against its recorded checksum and byte size; refresh = TRUE checks main again. The artifacts are not distributed in the CRAN package.

The detailed, itemized record of these changes is maintained in NEWS.

Current caveats

High-dimensional searches remain sensitive to initialization and random state, and some intermediate proposals can fail to converge. The compatibility initializer preserves an earlier strategy; it does not establish that a particular shift count or fitted model is optimal. Convergence diagnostics and handling are tracked in issue #242.

The Gumbel KL-divergence bootstrap has a known numerical limitation: overflow or underflow can discard valid large draws and make its confidence interval understate uncertainty. Do not rely on the affected interval as a dependable uncertainty estimate. The correction is deferred in issue #231 and is not included in the 0.2.2 release.

Some repository workflows and their methodological guidance remain under active development, especially pGLS-style uses of bifrost with hidden branch-specific rate variation. The simulation framework continues to use the original manuscript generator by default; the empirically calibrated full-covariance generator is available only when explicitly selected.

Repository automation and generated site assets, including the CRAN downloads tracker, support package development and documentation but are not part of the core CRAN API.

Website articles, example data, and the package tarball

The source files for the website articles and their empirical artifacts are maintained in this repository but excluded from the CRAN source-package tarball. Starting with 0.2.1, GitHub-generated source archives also exclude these materials, along with website configuration and development tooling. Zenodo’s GitHub integration captures that filtered source archive. Repository clones retain the complete tracked source, and the rendered articles remain available on the pkgdown website. Readers can explicitly request checksum-verified artifacts with bifrost_example_file(); later calls reuse the verified local cache. Package installation, attachment, and routine checks remain network-free.

For public-release information, use the CRAN package page. For the full change record, consult NEWS and the GitHub repository.