icTrajectory: Create an Information-Criterion Trajectory

In bifrost: Branch-Level Inference Framework for Recognizing Optimal Shifts in Traits

Create an Information-Criterion Trajectory

Description

Extract a standardized information-criterion (IC) trajectory from a completed bifrost_search object or a compatible search-result list.

Usage

icTrajectory(x, baseline_ic = NULL, ...)

Arguments

x	A bifrost_search object returned by searchOptimalConfiguration() with store_model_fit_history = TRUE, or a compatible list with baseline_ic and model_fit_history.
baseline_ic	Optional finite numeric baseline IC. When supplied, this value is used for step = 0 instead of x$baseline_ic. This is useful for legacy search-like lists that did not store baseline_ic.
...	Reserved for future extensions.

Details

icTrajectory() is a lightweight extractor. It does not refit models or recompute the search. The baseline IC is taken from x$baseline_ic unless baseline_ic is supplied, and is always included as step = 0; later rows summarize the stored proposal history in x$model_fit_history$fits. When a legacy object stores a historical x$model_fit_history$ic_acceptance_matrix, those matrix values are used to fill missing proposal IC or acceptance values. Objects that only contain the legacy matrix are also supported. In legacy cases without explicit proposal metadata, candidate_node cannot be recovered, and regime_id is inferred from proposal order because bifrost assigns candidate shift regimes sequentially during the search.

The returned object is a data frame with class c("icTrajectory", "data.frame") and the following columns:

• step: search step, with 0 reserved for the baseline.

• ic: IC for the baseline or evaluated proposal.

• accepted: proposal decision; NA for the baseline.

• best_ic: running best IC after each step.

• delta_ic: proposal improvement over the current best before the proposal; positive values indicate improvement.

• status: "baseline", "accepted", "rejected", or "error".

• candidate_node: phylogenetic node where the shift was evaluated.

• regime_id: mapped-state/regime label assigned to the evaluated candidate shift. The baseline row uses "0".

• error: optional error message.

Value

A data frame with class c("icTrajectory", "data.frame").

Examples

search <- list(
  baseline_ic = -1000,
  IC_used = "GIC",
  model_fit_history = list(
    fits = list(
      list(
        step = 1, candidate_node = 42, regime_id = "1",
        ic = -1010, accepted = TRUE, delta_ic = 10
      ),
      list(
        step = 2, candidate_node = 57, regime_id = "2",
        ic = -1008, accepted = FALSE, delta_ic = -2
      )
    )
  )
)
class(search) <- c("bifrost_search", "list")
traj <- icTrajectory(search)
legacy_traj <- icTrajectory(search, baseline_ic = -995)
plot(traj)

bifrost documentation built on Nov. 5, 2026, 9:07 a.m.