rateMapRateFlags: Control Near-Zero and Tail Rate Diagnostics for 'rateMap()'

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

Control Near-Zero and Tail Rate Diagnostics for rateMap()

Description

Build a rate-flagging control object for rateMapControl(). These options identify branch-rate summaries that are effectively zero, or optionally in a separated high-rate tail, without deleting or changing the fitted rates. Flags are reported in the returned intervals table and summarized in rate_diagnostics.

Usage

rateMapRateFlags(
  near_zero = NULL,
  high_outlier = FALSE,
  method = NULL,
  zero_floor = NULL,
  cluster_min_log_gap = log(10),
  cluster_min_fold_reduction = 10,
  cluster_max_tail_fraction = 0.4,
  cluster_min_flagged = 3,
  cluster_min_regular = 10,
  zero_label = "near-zero",
  high_label = "high-outlier",
  zero_color = "grey70",
  high_color = "black"
)

Arguments

near_zero	Logical or NULL. If TRUE, flag lower-tail or floor-level rates. The default NULL resolves to FALSE for method = "none" and TRUE for method = "floor" or method = "tail_cluster".
high_outlier	Logical; if TRUE, flag isolated upper-tail rates.
method	Optional detection method. NULL chooses "floor" when zero_floor is supplied and "none" otherwise. "floor" uses zero_floor for near-zero rates. "tail_cluster" uses an Otsu-style guarded two-class split of log rates to identify a separated lower-tail cluster, and, when high_outlier = TRUE, a separated upper-tail cluster. "none" computes diagnostics without adding special rate flags. Inactive switches are normalized to FALSE: method = "none" sets near_zero and high_outlier to FALSE, and method = "floor" sets high_outlier to FALSE.
zero_floor	Optional non-negative rate floor. When supplied with method = NULL, the method resolves to "floor". Finite rates less than or equal to this value are flagged as near-zero.
cluster_min_log_gap	Minimum log-rate gap required between a cluster-defined tail and the remaining regular rates.
cluster_min_fold_reduction	Minimum fold-range reduction required after separating a cluster-defined tail from the regular rates.
cluster_max_tail_fraction	Maximum fraction of positive finite rates that can be assigned to a cluster-defined tail.
cluster_min_flagged	Minimum number of branches required for a cluster-defined tail.
cluster_min_regular	Minimum number of branches that must remain in the regular rate set after separating a cluster-defined tail.
zero_label, high_label	Labels used for flagged display categories.
zero_color, high_color	Colors used for flagged display categories in category mode.

Details

The "tail_cluster" method is an Otsu-style diagnostic adapted to sorted branch log rates. It evaluates two-class splits and keeps a tail only when guardrails for log-rate gap size, fold-range reduction, tail fraction, and minimum counts are all satisfied. It is display metadata, not data deletion, model correction, or formal threshold selection.

Value

A normalized "rateMap_rate_flags" object for rateMapControl(rate_flags = ).

References

Otsu, N. (1979). A threshold selection method from gray-level histograms. IEEE Transactions on Systems, Man, and Cybernetics, 9(1), 62-66. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1109/TSMC.1979.4310076")}

Examples

floor_flags <- rateMapRateFlags(zero_floor = 1e-8)
floor_flags[c("method", "near_zero", "zero_floor")]

tail_flags <- rateMapRateFlags(
  method = "tail_cluster",
  high_outlier = TRUE
)
tail_flags[c("method", "near_zero", "high_outlier")]

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