bambootex

Convert pandas DataFrames into LaTeX/PDF tables using tabularray.

Requirements

• Python >= 3.11
• A TeX distribution with pdflatex (e.g. TeX Live)
• The following LaTeX packages: tabularray, siunitx, xcolor, babel, lmodern, fontenc

Installation

pip install bambootex

Quick start

import pandas as pd
from bambootex import Table, Cell, Font, Size, TextFormatter, GradientHighlighter, SimpleHighlighter

df = pd.read_csv("iris.csv")

tbl = Table(
    df,
    columns=["species", "sepal_length", "sepal_width"],
    column_formatters={
        "species": TextFormatter(font=Font.sf, size=Size.small),
    },
    headers=[
        [Cell("Species", vspan=2), Cell("Sepal", hspan=2)],
        [Cell(""), Cell("Length"), Cell("Width")],
    ],
    packages=["libertine"],
)

tbl.sort_by("sepal_length")
tbl.highlight("sepal_length", GradientHighlighter("white", "red"))
tbl.to_pdf("output.pdf")

API

Table

Table(
    df,                      # pd.DataFrame
    columns,                 # columns to include, in order
    column_formatters=None,  # dict of column -> format string, NumberFormatter, or TextFormatter
    headers=None,            # list of header rows, each a list of Cell
    packages=None,           # extra LaTeX packages to load
    number_format=".2f",     # default format for float columns (str or NumberFormatter)
    vlines=None,             # list of column indices to draw a vertical line after
    hlines=None,             # list of row indices to draw a horizontal line after
    default_size=None,       # document-wide font size (str or Size)
    merge_rows=None,         # column names whose consecutive equal values are merged into a row-spanning cell
)

Merging repeated cells vertically (merge_rows)

Consecutive rows with equal values in a merge_rows column are rendered as a single, vertically-centered, row-spanning cell instead of repeating the value on every row. This composes with .highlight(...): the merged cell's background is taken from the group's first row.

tbl = Table(
    df,
    columns=["dataset", "tool", "success"],
    merge_rows=["dataset"],
)

For finer control (e.g. spanning only some groups, or spanning multiple columns per cell), a column_formatters entry may return a Cell directly instead of a string — _build_content honors Cell.vspan/Cell.hspan the same way header cells do, covering the following rows/columns automatically.

.sort_by(key, reverse=False)

Sort rows before rendering. key can be a column name, list of column names, or a row-wise callable.

.highlight(column, highlighter, *fns)

Highlight cells in one or more columns.

• Single column (column: str): filter functions receive the full column series.
• Multiple columns (column: list[str]): a single predicate (value, row_subset) -> bool selects which cells to highlight per row.

# Gradient across all rows
tbl.highlight("score", GradientHighlighter("white", "red"))

# Highlight minimum per row across columns
tbl.highlight(
    ["time_a", "time_b", "time_c"],
    SimpleHighlighter("green!25"),
    lambda v, row: v == row.min(),
)

.to_tex(output_path) / .to_pdf(output_path)

Render to a .tex file or compile directly to PDF (requires pdflatex on $PATH).

---

Cell

Defines a header or body cell (see merge_rows above for body usage).

Cell(
    text,        # cell content
    hspan=1,     # columns to span
    vspan=1,     # rows to span
    align="c",   # tabularray halign: "l", "c", or "r"
    font=None,   # LaTeX font command, e.g. Font.tt or r"\texttt"
    valign=None, # tabularray valign: "t", "m", "b", "h", or "f"
    bg=None,     # xcolor color name to fill the cell background
)

---

TextFormatter

Applies LaTeX styling to a column's string values. When align is set, it also controls the column's alignment in the colspec.

TextFormatter(
    font=Font.sf,       # font command or list of font commands
    size=Size.small,    # size command
    align="c",          # column alignment ("l", "c", "r")
    prefix="(",         # prepended to each value
    suffix=")",         # appended to each value
)

---

NumberFormatter

Controls formatting of numeric columns.

NumberFormatter(
    decimal_places=2,   # decimal places
    unit=None,          # unit string appended after value
    nan=None,           # string to substitute for NaN values (e.g. "--")
)

---

Font

Font.rm   # \textrm
Font.sf   # \textsf
Font.tt   # \texttt
Font.bf   # \textbf
Font.it   # \textit

---

Size

Size.tiny / Size.scriptsize / Size.footnotesize / Size.small / Size.normalsize
Size.large / Size.Large / Size.LARGE / Size.huge / Size.Huge

---

Highlighters

Class	Args	Effect
SimpleHighlighter	color	Fills matching cells with a flat xcolor color
GradientHighlighter	color_min, color_max	Interpolates between two colors based on relative value

Any callable matching (series: pd.Series) -> dict[index, color_str] also works as a highlighter.