gradbars

Inline data graphics for LaTeX text and tables.

v1.1.0 · pdfLaTeX / XeLaTeX / LuaLaTeX · MIT

Released on 2026-10-25. Adds box plots, distribution summaries, shared legends, accessible palettes and optional tagged table structure.

简体中文 · English manual · Chinese manual · CTAN

Built on PGF/TikZ, gradbars embeds graphics in existing tabular cells or builds visual tables through declared gradtable columns and data rows. No tikzpicture wrapper or shell escape is required.

Features

• Inline graphics: data bars, signed bars, lollipops, comparisons, dumbbells, bullet charts, intervals, stacks, sparklines and heat cells.
• Visual tables: automatic widths, independent header alignment, spanning headers, groups, best/second-best marking, summaries and pagination.
• Data handling: CSV field binding, sorting, filtering, grouping, automatic column ranges and named shared scales.
• Numbers and appearance: scientific input, optional siunitx formatting, decimal alignment, themes, patterns, table styles and legends.
• Accessibility and extensions: automatic graphic alternative text when LaTeX PDF tagging is enabled, with alt overrides; stable registration interfaces for scalar graphics, formatters and contributed libraries.

Installation

Requires LaTeX 2025-11-01+, expl3 2025-12-29+ and PGF/TikZ 3.1.11a+. Update older distributions before installing this release.

The package is available on CTAN. For TeX Live or MacTeX managed by tlmgr:

tlmgr install gradbars

Update an installed copy or inspect package information:

tlmgr update gradbars
tlmgr info gradbars

The TeX Live repository may lag behind CTAN or the development repository. Check the installed version. For manual installation, copy all .sty files from sty/, including optional tblrlibgradbars.sty, beside your main .tex file, or install them in a local TEXMF tree under tex/latex/gradbars/. Do not copy only the entry file or mix module versions.

pdfLaTeX, XeLaTeX and LuaLaTeX are supported. Dependencies include PGF/TikZ, xparse and expl3; collected CSV columns and native tables additionally load collcell, array, booktabs, colortbl and longtable. siunitx is optional. The package itself does not load ctex or fontspec.

Quick start

Compile this complete example:

\documentclass{article}
\usepackage{gradbars}
\begin{document}
\gradbar[max=100,width=30mm,precision=1]{72.4}

\begin{gradtable}[width=\linewidth,header align=c]
  \gradcolumn{method}{Method}
  \gradcolumn[type=bar,mark=both,
    options={max=100,precision=1}]{score}{Score}
  \gradcolumn[type=number,mark=best,
    options={better=lower,precision=1}]{time}{Time / ms}
  \gradrow{Baseline,72.4,18.2}
  \gradrow{Proposed,92.7,11.5}
  \gradrow{Pending,NA,NA}
\end{gradtable}
\end{document}

Higher scores and lower times are better. mark=both marks the best and second-best values. NA denotes missing data, not zero. For Chinese content, use an appropriate setup such as XeLaTeX with ctexart.

Loading selected libraries

By default, \usepackage{gradbars} loads all features. Select libraries explicitly with:

\usepackage[libraries={stack,spark,heat,csv,table}]{gradbars}

Use libraries=none for basic graphics only. Additional libraries must be loaded in the preamble:

\usepackage[libraries=none]{gradbars}
\usegradbarslibrary{stack,spark}

all and none are modes of the libraries option, not library names. Both \gradbarsset and \gradbarssetup set defaults within the current scope.

Ordinary tables with numeric cells

\gradbarscolumn*{G}{max=1,width=14mm,precision=3,theme=gray}
\begin{tabular}{lGG}
Method & \gradbarshead{Precision} & \gradbarshead{Recall}\\
Alpha & 1.000 & 0.968\\
Beta & & 0.750\\
\end{tabular}

tabularray integration

With tabularray 2025C (2025-11-27) or newer, load the optional adapter in the preamble:

\usepackage{tabularray}
\usepackage{gradbars}
\UseTblrLibrary{gradbars}

G[options]{width}, H[options]{width}, N[options]{width} and D[options]{width} provide bars, heat cells, numbers and layered comparisons. Protect headers with {...}. Cell helpers such as \gradbarTblr also work with existing Q/X columns. label align=cell centers inside/auto labels across the content area; label=left preserves formatted numbers and units. The separate gradtblr environment supplies preset styling, while native gradtable supports style=matrix. Ordinary documents do not load tabularray automatically. Both manuals include a dedicated integration chapter.

Data and layout conventions

• Use consistent ranges to compare the same metric. Automatic spark ranges emphasize shape; fix the scale to compare absolute levels.
• Formatting does not alter raw calculations. unit appends text; value format=percent computes the value relative to max.
• CSV accepts single-line comma-separated fields read as characters, not executed as TeX. Sparklines use equally spaced observations and do not parse dates.
• Signed stacks accumulate independently on each side of zero. The default total is the net sum; segment percentages represent shares of absolute contributions.
• long=true enables native table pagination. Place multipage tables in single-column body text, outside floats and minipages.
• Automatic alternative text covers graphics only. Document reading order, table structure and other accessibility requirements need separate validation.

Documentation and development

Both manuals pair rendered output with source and cover getting started, graphics, appearance, tables, applications and reference material.

• Chinese main source and Chinese chapters.
• English main source and English chapters.
• Source guide for the l3doc and docstrip workflow.
• Changelog for additions, fixes and compatibility changes.

Runtime modules live in sty/; the contributed example lives in docs/libraries/. From the repository root, run:

l3build check
texlua scripts/check.lua
texlua scripts/source.lua --check
l3build doc

The build uses TeX Live texlua, l3build and latexmk, without Python. The Chinese manual uses XeLaTeX; the English manual and source guide use pdfLaTeX. latexmk handles reruns automatically. PDFs are distributed as GitHub Release assets rather than committed to Git.

gradbars.dtx and gradbars.ins are reproducible distribution sources; texlua scripts/unpack.lua creates sty/ if needed and extracts all 22 runtime modules there, leaving the source root free of .sty files. Alternatively, retain the supplied sty/README.md and run tex gradbars.ins. Neither command requires shell escape. After editing sty/, run texlua scripts/source.lua to synchronize them. Inspect actual Figure alternatives and tagged table spans/scopes with texlua scripts/pdf-check.lua.

See release configuration. The CTAN source ZIP excludes Python files and generated runtime modules; the development repository retains sty/.

Feedback and license

Report problems through GitHub Issues, including a minimal .tex example, engine, package version and relevant log.

Author and maintainer: SuFan (GitHub: Tape5try). Licensed under MIT. Full regression tests require the GitHub development checkout; this CTAN source package contains the documentation and installation sources.