ucs_histo

把数值分布生成可读的终端直方图，支持线性、对数、分位数和离群值感知分桶

Release: UCS-2.1.0 · 2026-07-24
Input: 文件、命令行数值或标准输入
Default: Outlier-aware · 50 buckets · width 80
License: 启动时检查 UCS license

1. Quick Start

# 文件中由空白分隔的所有数字
./ucs_histo slack_values.txt

# stdin
awk '{print $NF}' timing_summary.txt | ./ucs_histo -s outlier_aware -b 30

# 直接传数值；负数前用 --
./ucs_histo -s linear -b 8 -- -2 -1 -0.5 0 0.2 0.5 1 2

# 写文件
./ucs_histo data.txt -o slack_histogram.txt

恰好一个参数且它是存在的文件时读取该文件；有多个参数时把参数视为数值 tokens；无参数时读取 stdin。不能解析为数值的 token 会忽略；一个有效数值都没有则报错。

2. 分桶 Strategy

Strategy	算法	建议
`linear`	min 到 max 等宽分桶。	范围有限、分布比较均匀。
`log`	对正数按对数尺度分桶；存在正数时非正数不进入 log histogram；全部非正时回退 linear。	跨多个数量级的正值。
`quantile`	按排序后的样本数量近似均分。	关注各区间拥有相近样本数。
`outlier_aware`	以 IQR 判断主分布，把极端值放入边缘桶。	STA slack、delay 等含少量极端值的数据；默认。
`auto`	正值 max/min > 100 时选 log；否则发现 IQR outlier 时选 outlier-aware；其余 linear。	不确定分布类型时。

Outlier-aware 的价值：极少数严重值不会把主体 bucket 压缩在图的一小段；但离群样本没有被删除，仍在边缘桶计数。

3. Command-Line Reference

Usage: ucs_histo [OPTIONS] [FILE_OR_NUMBER]...

  -s, --strategy <auto|linear|log|quantile|outlier_aware>
  -b, --buckets <N>      [default: 50; N >= 2]
  -w, --width <N>        [default: 80; N >= 10]
  -o, --output <FILE>
  -t, --trim <FRACTION>  [default: 0; 0..0.5]
  -r, --threshold <N>    [default: 1.5; N > 0]
  -h, --help
  -V, --version

--trim 0.01 会从排序后两端各去掉约 1% 样本，再画图；这是显式丢弃样本，与 outlier-aware 仅改变分桶不同。只有确实需要排除测量异常时才使用 trim。

--threshold 是 outlier-aware 的 IQR multiplier。默认 1.5；更大值把更少样本视为离群值。

4. 使用案例

4.1 STA slack 主体与极端值

rg -o "slack.*?(-?[0-9]+\\.[0-9]+)" report_timing.rpt \
  | awk '{print $NF}' \
  | ./ucs_histo --strategy outlier_aware --buckets 40 --width 100

4.2 正值跨数量级

./ucs_histo capacitance.txt --strategy log --buckets 25

4.3 每个 bucket 样本数接近

./ucs_histo transition.txt --strategy quantile --buckets 10

4.4 保存结果供 handoff

./ucs_histo route_delay.txt -s auto -b 30 -w 100 \
  -o route_delay_histogram.txt

指定 output 后 histogram 写入文件，stdout 只打印输出位置确认，便于脚本判断交付文件。

5. Troubleshooting

现象	原因与处理
负数被识别为 option	命令行直接传负数时先写 `--`；从文件或 stdin 输入不需要。
log 少了 0/负值	log 只接受正数。含正负 slack 的分布使用 linear、quantile 或 outlier-aware。
bucket 少于指定数量	bucket 数不会超过有效样本数。
图仍被异常值拉宽	使用 outlier-aware，或适当降低/提高 threshold；需要明确删除两端时才用 trim。
No numeric values	输入 tokens 都无法解析为数值；先检查抽取列和单位字符。

验证：五种 strategy、文件/参数/stdin、负数、trim、threshold 和 output 均按 UCS-2.1.0 当前实现核对。