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

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.

Value

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

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.

References

Otsu, N. (1979). A threshold selection method from gray-level histograms. IEEE Transactions on Systems, Man, and Cybernetics, 9(1), 62-66. doi:10.1109/TSMC.1979.4310076

Examples

if (FALSE) { # \dontrun{
ctrl <- rateMapControl(rate_flags = rateMapRateFlags(zero_floor = 1e-8))
rm_obj <- rateMap(fits, control = ctrl)
rm_obj$rate_diagnostics

cluster_ctrl <- rateMapControl(
  rate_flags = rateMapRateFlags(method = "tail_cluster")
)
rm_obj <- rateMap(fits, control = cluster_ctrl)
rm_obj$rate_diagnostics
} # }