Changelog

Source: NEWS.md

bifrost 0.2.0

• Baseline-only search results now consistently retain regime label "0" and include the fitted global BM covariance in VCVs[["0"]], without an additional fit. Covariance summaries no longer warn about proportional multi-regime matrices for this single global covariance. Search decisions are unchanged.

• Simulation tuning:

  • runSearchTuningGrid() now pairs simulated datasets across all settings, using shared scenario seeds consistently in serial and parallel execution. Separate GIC and BIC calls with matching simulation inputs and seeds are also paired. Its arguments are unchanged; returned objects record paired_settings and study_seeds. Previously seeded grid results will change under this sampling design; existing cached results are not replaced.

• Search progress:

  • searchOptimalConfiguration() now displays persistent, Future-compatible CLI progress for candidate scoring, greedy shift evaluation, and IC-weight re-estimation by default.
  • Reached stage rows remain stacked at the bottom while verbose = TRUE output streams above them.
  • Stage spinners now redraw continuously during long model fits while completion counts, percentages, and ETA advance only after a fit finishes.
  • Added progress = FALSE as an explicit opt-out independent of detailed verbose messages.
  • Captured expression-valued search inputs now print safely in print.bifrost_search() output.

• Search inputs and diagnostics:

  • Formula-based searches now accept formula objects as well as character strings, numeric response-only data frames for intercept-only searches, and named-column data-frame formulas for pGLS-style workflows.

  • When IC = "BIC" and method is omitted, searches now use method = "LL"; an explicitly supplied method still takes precedence. GIC searches continue to use the mvgls() fitting-method default when method is omitted.

  • Added icTrajectory() and its plot() method for inspecting stored search histories.

  • Removed the superseded plot_ic_acceptance_matrix() wrapper. For a bifrost_search or compatible search-result list, migrate to plot(icTrajectory(x)).

  • Legacy callers that passed a raw two-column matrix_data object must wrap it as a search-like list before plotting:

    legacy <- list(
      baseline_ic = baseline_ic,
      IC_used = "GIC",
      model_fit_history = list(ic_acceptance_matrix = matrix_data)
    )
    plot(icTrajectory(legacy))

    The former plotting arguments map as follows: plot_title to main, plot_rate_of_improvement to show_delta, rate_limits to delta_limits, and baseline_ic to the icTrajectory() call.

  • Search results now include candidate_nodes, and user_input records the resolved progress setting. Stored model-fit histories retain proposal step, node, regime, IC, status, and explicit accepted, rejected, and errored records.

  • Search input validation now requires an integer of at least 2 for min_descendant_tips and rejects simultaneous uncertaintyweights = TRUE and uncertaintyweights_par = TRUE before fitting begins.

  • Search input validation now also rejects missing, nonscalar, nonnumeric, nonfinite, and negative shift_acceptance_threshold values before fitting begins.

  • Search diagnostics now flag minimum clade sizes below 10 and IC acceptance thresholds below 10, contextualize the simulation and focal settings from Berv et al. (2026), report when no non-root candidates are eligible, and reject descendant-tip cutoffs larger than the tree. Repeated simulation searches muffle only the classed settings advisory while preserving fitting and optimizer warnings.

  • Search controls now default to min_descendant_tips = 10 and shift_acceptance_threshold = 20, matching the focal settings of Berv et al.

    2026. and providing conservative empirical starting points.

• Branch-rate summaries:

  • Added the rateMap() workflow and supporting view, control, flagging, print, and plot methods for summarizing branch-rate patterns across completed searches.
  • Category legends represent uneven rate breaks proportionally, with strengthened validation of category-color counts.
  • generateViridisColorScale() now explicitly requires numeric input, and its documentation clarifies that colors encode sorted rank rather than numeric magnitude or distance.

• Lineage-rate and shift-distribution analyses:

  • Added lineage_rates() for tip-level summaries of inherited rate histories and associated branch and shift diagnostics.
  • Added tools for extracting shift nodes, transitions, waiting times, and magnitude groups; fitting waiting-time and lineage-rate distributions; bootstrapping rate-distribution summaries; and comparing shift magnitudes.

• Regime covariance and integration analyses:

  • Added fit_regime_covariances(), fit_regime_covariance_runs(), and their summary helpers for post-hoc covariance estimation across fitted regimes and search runs.
  • Added module diagnostics, correlation-matrix PCA, integration-relationship summaries, and regime_integration_pgls() for examining regime-specific covariance structure and downstream relationships.

• Simulation studies and tuning:

  • Fixed recovery evaluation excluding successful searches with an explicitly NULL shift-node vector. Zero-shift results now contribute missed shifts to strict, fuzzy, and weighted recovery summaries; saved results can be reassessed without refitting searches. Failed or incomplete records remain excluded.
  • Added reproducible simulation templates, null and shifted dataset generators, false-positive and shift-recovery studies, recovery evaluation, and fixed-IC tuning grids.
  • Added empirical null, proportional-shift, and integration-rate robustness workflows centered on fitted residual covariance, with simulation_generator = c("original", "empirical") for explicit generator selection.
  • The new simulation generators default to "original" for exact reproduction of the published operations; the full-covariance Wishart/spectral generator remains available explicitly as simulation_generator = "empirical".
  • selectTunedSearchParameters() filters settings using null false-positive and evaluability safeguards, then ranks feasible settings by fuzzy balanced accuracy by default.
  • Reduced multisession transfer size by using compact namespace-level workers and by avoiding a complete calibration template inside every replicate’s call record.

• Documentation / vignettes:

  • All vignettes are now website-only. The source package and installed package no longer include vignettes/ or built inst/doc articles; the complete worked documentation remains available on the package website.
  • Removed all former system.file("extdata", ...) empirical paths intentionally. Use bifrost_example_file() instead for the eight named artifacts: jaw-tree, jaw-landmarks, passerine-tree, passerine-traits, passerine-search, passerine-sensitivity, passerine-posthoc, and simulation-preview-tables.
  • Reduced installed package size by no longer distributing repository/site empirical payloads through CRAN. Normal package installation, attachment, examples, and checks remain network-free.
  • Documented that the first uncached bifrost_example_file() request uses the checksum-verified artifact currently tracked on GitHub main; later calls reuse the verified cache unless refresh = TRUE requests a new check.
  • Added small, deterministic, runnable help examples for regime-integration, simulation, rate-map, lineage-rate, and tuning workflows; longer model-fitting examples now use bounded \donttest{} blocks that are exercised in CI.
  • Added two rate-map jaw-shape workflows and refreshed the existing jaw-shape vignette.
  • Added a five-part avian skeleton case study covering search inspection, lineage rates, shift distributions, magnitude comparisons, and post-hoc covariance and integration analyses.
  • Added a two-part empirically calibrated simulation guide covering performance assessment, search tuning, and empirical application.
  • Added downloadable vignette PDFs and executable Colab notebooks to the website articles.
  • Updated Berv et al. (2026) citation metadata and avian skeleton references for the published Nature Ecology & Evolution article DOI.

• Maintenance:

  • Increased the minimum supported R version from 4.1 to 4.2.
  • Added minimum versions future (>= 1.49.0) and phytools (>= 2.0-3), corrected runtime and optional dependency declarations, moved website-only packages to Config/Needs/website, and removed VignetteBuilder because vignettes are not built into the package.
  • Added plotrix as a direct dependency for rate-map arc and fan geometry.
  • Refactored searchOptimalConfiguration() into dedicated internal helpers for candidate evaluation, greedy search orchestration, history bookkeeping, and parallel result handling; the public entry point remains searchOptimalConfiguration(), and existing positional arguments remain compatible.
  • Parallel search and simulation paths preserve the caller’s Future plan and reproducible RNG state while avoiding nested worker oversubscription.
  • Hardened lineage-rate, regime-integration, simulation, and tuning workflows around malformed inputs, failed fits, reproducible parallel execution, and infeasible selections.
  • Added a CRAN downloads chart to the README and development website.

bifrost 0.1.4

CRAN release: 2026-04-17

• Documentation / vignettes:
  • Added a new “Quick Start with bifrost” vignette with a minimal end-to-end simulated example.
  • Clarified searchOptimalConfiguration() documentation around acceptable tree inputs, recommended mvgls() methods ("H&L" vs "LL"), and the role of error = TRUE.
  • Reworked the README to foreground installation, documentation, and citation guidance.
  • Added two pkgdown-only background articles on multivariate Brownian motion / shifts and on whole-tree PCA / model-selection issues.
• Citation / metadata:
  • Updated package authorship metadata to reflect the current author list.
  • Updated citation("bifrost") for the live bioRxiv preprint and the application paper.
  • Added the foundational mvMORPH citations to the package citation metadata.
  • Added a formatted citation section and dynamic bioRxiv badge to the README.
• Maintenance:
  • Disabled a deprecated vignette-preview step in GitHub Actions CI.

bifrost 0.1.3

CRAN release: 2026-01-21

• Addressed CRAN reviewer feedback following review of 0.1.2:
  • Added explicit return-value documentation (@return / \value{}) for the exported print.bifrost_search() method, clarifying that the function returns the input object invisibly and is called for its printing side effects.
• Plotting:
  • plot_ic_acceptance_matrix() gains an optional baseline_ic argument to plot and compute diff(IC) relative to the true no-shift baseline (useful when matrix_data begins at the first evaluated shift model rather than the true baseline).
• Documentation / vignettes:
  • Updated the jaw-shape vignette with additional static figures (evolutionary correlation heatmap, IC-trajectory plot, and branch-rate visualization) and improved plotting annotations.

bifrost 0.1.2

• Addressed CRAN reviewer feedback following review of 0.1.1:
  • plot_ic_acceptance_matrix() now saves and restores the user’s graphical parameters via an immediate on.exit() (prevents leaking par() settings across calls).
• Plotting:
  • Added rate_limits argument to plot_ic_acceptance_matrix() (default c(-400, 150)) to control the secondary y-axis limits for the rate-of-improvement overlay (validated numeric length-2, finite).
• Search results output:
  • Added a bifrost_search S3 class and print.bifrost_search() method for searchOptimalConfiguration() results (compact console summary; optional ASCII IC-history plot via txtplot when store_model_fit_history = TRUE; prints IC weights when present).
  • Print output includes a citation hint (citation("bifrost")); package citation metadata updated in inst/CITATION.
• IC weights / no-shift behavior:
  • Standardized ic_weights output across serial and parallel uncertainty-weight modes; always returns a data.frame with consistent columns, and returns an empty data.frame with the same schema when no shifts are detected.
  • When no shifts are detected, model_no_uncertainty now returns the baseline mvgls model (instead of NULL).
• Documentation / vignettes / tests:
  • Updated jaw-shape vignette chunk printing of ic_weights to avoid RStudio paged/Unicode rendering issues.
  • Expanded and stabilized unit tests and CI configuration (including Config/testthat/parallel: false).

bifrost 0.1.1

• Addressed CRAN reviewer feedback following review of 0.1.0:
  • Replaced all uses of shorthand T/F with TRUE/FALSE.
  • Ensured all informational output is suppressible via message()/warning() and controlled by a verbose flag.
  • Redirected all on-disk output generated during model fitting to tempdir() to comply with CRAN file system policies and avoid writing to the user’s working directory.
  • Ensured graphical parameters and global options are restored using immediate on.exit() calls.
  • Refined parallelization behavior to be CRAN-safe and cross-platform:
    • Parallel candidate evaluation uses future with multicore on Unix outside RStudio and multisession otherwise.
    • BLAS/OpenMP threads are capped to one per worker during parallel execution to avoid CPU oversubscription.
    • Sequential execution remains the default when num_cores = 1.
  • Improved documentation clarity around parallel execution, verbosity, and model fit history storage.

bifrost 0.1.0

• Initial CRAN submission.