Tables and CSV

表格与 CSV

适用版本：v1.1.0。快速入门 · 案例库

三种表格入口

入口	适用需求
普通 tabular / longtable + \gradbarscolumn*	保留已有排版，单元格只填数字
原生 gradtable	列声明、数据绑定、自动尺度、排序筛选和统计汇总
tabularray + \UseTblrLibrary{gradbars}	与 tblr/longtblr 的列和单元格接口融合

普通收集列不自动排名、汇总或推断范围；需要这些处理时选择 gradtable。

CSV 绑定、筛选、排序与汇总

在主文件旁保存 results.csv：

Model,Score,Latency
Baseline,72.4,125
Model A,81.6,88
Proposed,92.7,61
Pending,NA,NA

完整文档：

\documentclass{article}
\usepackage{gradbars}
\begin{document}
\gradbarsloadcsv{results}{results.csv}
\begin{center}
\begin{gradtable}[align=c,header align=c,width=\linewidth,
  data=results,scale=column,filter={score>=75},
  sort=time,order=ascending,limit=2]
\gradcolumn[source=Model]{method}{Method}
\gradcolumn[type=bar,source=Score,mark=both,
  aggregate=mean,options={precision=1}]{score}{Score}
\gradcolumn[type=number,source=Latency,
  options={better=lower,precision=0}]{time}{Latency}
\gradsummary{Mean}
\end{gradtable}
\end{center}
\end{document}

• source 精确匹配 CSV 表头，sort 和 filter 使用已声明的列标识。
• 处理顺序为筛选、稳定排序、limit。普通比较排除缺失；使用 score=NA 或 score!=NA 检查缺失。
• scale scope=data 默认按完整数据确定范围；visible 只按展示行。排名按筛选和 limit 后保留的行计算；范围和排名不是同一个设置。
• aggregate 支持 count/sum/mean/min/max，缺失不参与，零参与。\gradsummary 默认汇总展示行，scope=data 可汇总完整数据。
• CSV 字段按字符读取，不执行 TeX。仅支持逗号分隔、单行字段；含逗号字段用双引号，字段内引号写成两个双引号。不能把手写 \gradrow 与导入数据混用。

范围、间距与跨页

scale=column 自动扫描同列数据。跨表比较可声明 \gradscale{score}{min=0,max=100}，再使用 scale group=score；表格列使用命名尺度时应选 scale=fixed。

图形宽度、标签宽度、column sep 和行距共同决定表格尺寸。先减少不必要的间距，再考虑字体缩小。普通表格放入 center，列与表头使用适当的对齐配置。

long=true 支持原生表格跨页与重复表头。必须放在单栏正文，不能放进浮动体或 minipage。跨页表格保持列宽、范围和排名一致。

tabularray

\documentclass{article}
\usepackage{tabularray}
\usepackage{gradbars}
\UseTblrLibrary{gradbars}
\begin{document}
\begin{center}
\begin{tblr}{colspec={c G[min=0,max=100]{35mm}}}
{Method} & {Score}\\
Alpha & 72\\
Beta & 90\\
\end{tblr}
\end{center}
\end{document}

表头用 {...} 保护。适配器需要 tabularray 2025C（2025-11-27）或更新版本。G/H/N/D 分别提供条形、Heat、数字和双层比较，另有 J/R/V/K/U/B 对应哑铃、区间、趋势、堆叠、子弹图和箱线图。

普通列详细说明 · API 参考