gradbars

Compact data graphics inside ordinary LaTeX tables.

v0.0.3 · pdfLaTeX / XeLaTeX / LuaLaTeX · MIT

Author and maintainer

gradbars is authored and maintained by SuFan (苏凡). Tape5try is SuFan's GitHub username, not a separate author. Contact: 3546236610@qq.com. Copyright (c) 2026 SuFan. Distributed under the MIT License.

中文说明 · English manual PDF · 中文手册 PDF · API reference · Release notes

Use a consistent scale, keep real numbers visible, and add a small graphic directly to a table cell. No tikzpicture wrapper or shell escape is required.

New in v0.0.3

• Dumbbell comparisons: hollow reference points, filled current points, optional current-minus-reference labels.
• Signed stacks: accumulate positive and negative contributions independently; show the net or both subtotals.
• Sparklines: equally spaced observations, gaps for missing values, extrema and last-point markers, automatic or shared fixed ranges.
• Target and interval quality: evaluate distance from a goal or acceptable interval without changing data geometry.
• Semantic palettes: categorical, sequential, diverging and monochrome schemes; named categories keep their colors and patterns when reordered.
• One reorganized manual: 56 numbered output/source examples, six application tables, four real layout cases and an interface index.

Existing bars, lollipops, layered comparisons, floating intervals, error whiskers, CSV input, numeric table columns and named styles remain available.

Quick start

Copy gradbars.sty next to your main .tex file. The package works with pdfLaTeX, XeLaTeX and LuaLaTeX. The package uses TikZ, xparse, expl3 and collcell, available in standard TeX installations. Chinese fonts are needed only for the Chinese manual, not for the package.

\documentclass{article}
\usepackage{booktabs,gradbars}
\begin{document}
\gradbarssetup{width=35mm,precision=0}
\begin{tabular}{ll}
\toprule
View & Data \\
\midrule
Single value & \gradbar{72} \\
Current / reference & \graddumbbell{58}{76} \\
Positive / negative & \gradstack[min=-50,stack totals=separate]{60,-20,15,-10} \\
Trend / last value & \gradspark[spark range=fixed,min=0,max=100]{25,45,NA,60,80} \\
\bottomrule
\end{tabular}
\end{document}

Choose a graphic

Preserve data meaning

• Bars share explicit min, max and width. Zero stays at zero; negative values require a negative minimum.
• unit appends text. value format=percent computes value/max only for nonnegative ranges. Formatting never changes geometry.
• Empty input or NA denotes missing data. A missing spark observation breaks the line and retains its horizontal position.
• Signed stacks accumulate from zero independently on each side. The default total is the algebraic sum; stack totals=separate shows positive / negative subtotals.
• Stack segment percentages use abs(segment) / sum(abs(segments)). They are shares of absolute activity, not of the net balance. Stacks do not automatically normalize to full width.
• Auto-scaled sparklines compare shapes. Use spark range=fixed with the same min, max, width and height to compare levels across rows.
• Overflow warns and clips the drawing while retaining raw labels; use overflow=error for strict checking.

Express quality separately

% Within 5 of the goal is good; within 15 is intermediate.
\gradbar[better=target,quality target=50,
  thresholds={5,15},target=50,palette=diverging]{52}

% Inside [40,60] is good; no more than 10 away is intermediate.
\gradbar[better=interval,quality range={40,60},
  thresholds={0,10},band={40,60},palette=diverging]{68}

threshold colors always lists bad, intermediate, good. In target/interval modes, thresholds are nonnegative distances with inclusive upper boundaries. quality target / quality range evaluate data; target / band draw references. better=higher|lower remains available for monotonic metrics.

Reuse appearance and category identity

\gradbarsstyle{paperrow}{preset=paper,width=40mm,max=100,precision=1}
\gradbar[style=paperrow]{82.5}

\gradbarscategory{Compute}{gradbarsBlue}{diagonal}
\gradbarscategory{Storage}{gradbarsOrange}{dots}
\gradstack[stack names={Compute,Storage}]{60,30}
\gradstack[stack names={Storage,Compute}]{30,60}
\gradbarslegend{Compute,Storage}

Four layout presets: paper, report, presentation, outline. Four group palettes: categorical, sequential, diverging, mono. Seven themes and nine original solid colors remain available. Unregistered categories use cyclic position-based palettes; registered names preserve their assigned color and pattern. In print/mono mode category colors use the grayscale palette, while registered patterns remain. Legends use the same mapping as segments.

CSV and existing tables

\gradbarsloadcsv{results}{results.csv}
\gradbarscsvstyle{shared}{results}{Score}
\gradbarcsv[style=shared]{results}{1}{Score}
\gradbarscolumn{G}{style=shared}

CSV fields are read as character data, not executed as TeX. Named columns, quoted commas, custom missing tokens and shared column ranges are supported. See the manual for complete tables.

Documentation and building

The single Chinese manual is organized into quick start, graphic selection, data interfaces, appearance, complete layouts, and reference. It contains 56 numbered examples, including before/after evaluation, a monochrome contribution ledger and a monthly trend summary. All example data are illustrative.

To generate the versioned PDF in the repository root:

python scripts/build_manual.py

The script rebuilds the four layouts and the Chinese manual with XeLaTeX, then the English manual with pdfLaTeX; each document gets two passes. It requires ctex/Fandol and the LaTeX extra packages; Python is only a documentation-build helper. Both versioned PDF manuals are included. The English source builds with pdfLaTeX; the Chinese manual uses XeLaTeX. All text files use LF line endings.

Scope and limits

• pdfLaTeX, XeLaTeX and LuaLaTeX have passed package checks including CSV input. Only the Chinese documentation requires the XeLaTeX/ctex workflow. This is a table-oriented interface, not a full plotting system.
• CSV accepts single-line comma-separated fields; automatic CSV tables do not paginate.
• Stacks reject missing segments, conditional thresholds and error whiskers.
• Sparklines use equally spaced observations; they do not parse dates or draw bar targets, error whiskers or reference bands.
• Fixed scales require min <= 0 and max > 0; auto spark ranges can be positive, negative or constant.
• Label avoidance is local to a graphic. Allow room for long external labels and legends.
• Accessible tagged chart descriptions and tabularray-specific column handling are not implemented.

MIT licensed. Bug reports should include a minimal .tex example, engine and log.