rendering - bossanova

LaTeX equation and markdown rendering for model output.

Call chain:

model.equation() -> build_equation(spec) -> LaTeX string
model_result.to_markdown() -> dataframe_to_markdown(df) -> markdown string

Functions:

Name	Description
`build_equation`	Build a structural LaTeX equation from model containers.
`dataframe_to_markdown`	Convert a Polars DataFrame to a pipe-delimited markdown table.
`equation_to_markdown`	Wrap a LaTeX equation in display math delimiters for Quarto.
`to_markdown`	Convert a Polars DataFrame to a markdown table, optionally saving to file.
`write_text`	Write text content to a file, creating parent directories.

Modules:

Name	Description
`latex`	LaTeX equation generation from model containers.
`markdown`	Markdown table and equation rendering for report export.

Functions¶

build_equation¶

build_equation(spec: ModelSpec, bundle: DataBundle | None = None, formula_spec: FormulaSpec | None = None, *, explanations: bool = True) -> MathDisplay

Build a structural LaTeX equation from model containers.

Works in two modes:

Spec-only (no data): generic symbols from spec.fixed_terms.
With bundle: full rendering using bundle.X_names for exact column names, factor levels, contrast types, and transform parameters.

Parameters:

Name	Type	Description	Default
`spec`	`ModelSpec`	Model specification (always available).	required
`bundle`	`DataBundle \| None`	Data bundle (None before data is attached).	`None`
`formula_spec`	`FormulaSpec \| None`	Learned formula encoding (None before data is attached).	`None`
`explanations`	`bool`	Include term explanations in the output.	`True`

Returns:

Type	Description
`MathDisplay`	MathDisplay with equation, explanations, and rich display methods.

dataframe_to_markdown¶

dataframe_to_markdown(df: pl.DataFrame, caption: str | None = None) -> str

Convert a Polars DataFrame to a pipe-delimited markdown table.

Produces GitHub Flavored Markdown (GFM) table syntax that renders correctly in Quarto, GitHub, and most markdown environments. Columns are padded to align visually. Null values render as empty cells.

No additional numeric formatting is applied — the DataFrame is assumed to be pre-rounded (as all bossanova result DataFrames are).

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Polars DataFrame to convert.	required
`caption`	`str \| None`	Optional table caption. Rendered as `Table: {caption}` above the table (Quarto cross-reference syntax).	`None`

Returns:

Type	Description
`str`	Pipe-delimited markdown table as a string.

Examples:

>>> import polars as pl
>>> df = pl.DataFrame({"x": [1, 2], "y": [3.14, 2.72]})
>>> print(dataframe_to_markdown(df))
| x | y    |
|---|------|
| 1 | 3.14 |
| 2 | 2.72 |

equation_to_markdown¶

equation_to_markdown(equation: str, explanations: tuple[str, ...] = (), *, include_explanations: bool = True) -> str

Wrap a LaTeX equation in display math delimiters for Quarto.

Produces $$...$$ display math that Quarto renders natively in Typst, HTML, and PDF output. Optionally appends term explanations as plain text below the equation block.

Parameters:

Name	Type	Description	Default
`equation`	`str`	LaTeX equation string (without `$$` delimiters).	required
`explanations`	`tuple[str, ...]`	Term explanation strings from `MathDisplay`.	`()`
`include_explanations`	`bool`	If True (default), append explanations as plain text lines below the equation.	`True`

Returns:

Type	Description
`str`	Markdown string with display math block and optional explanations.

Examples:

>>> print(equation_to_markdown(r"y = \beta_0 + \beta_1 x"))
$$
y = \beta_0 + \beta_1 x
$$

to_markdown¶

to_markdown(df: pl.DataFrame, path: str | Path | None = None, caption: str | None = None) -> str

Convert a Polars DataFrame to a markdown table, optionally saving to file.

Standalone utility for DataFrames not wrapped in ModelResult — such as results from compare(), model.jointtest(), model.vif(), model.to_odds_ratio(), etc.

For ModelResult objects (returned by .fit(), .infer(), etc.), use result.to_markdown() instead.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Polars DataFrame to convert.	required
`path`	`str \| Path \| None`	Optional file path. If given, writes the markdown and creates parent directories automatically.	`None`
`caption`	`str \| None`	Optional table caption (`Table: ...` Quarto syntax).	`None`

Returns:

Type	Description
`str`	Pipe-delimited markdown table as a string.

Examples:

>>> from bossanova import compare, to_markdown
>>> to_markdown(compare(m1, m2), "comparison.md", caption="Model Comparison")
>>> md = to_markdown(m.jointtest())  # string only

write_text¶

write_text(text: str, path: str | Path) -> None

Write text content to a file, creating parent directories.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Destination file path. Parent directories are created automatically if they don’t exist.	required
`text`	`str`	Text content to write.	required

Modules¶

latex¶

LaTeX equation generation from model containers.

Pure functions that accept ModelSpec, DataBundle, and FormulaSpec containers and produce MathDisplay output. Works pre-data (spec-only) and post-data (with full factor/contrast/transform metadata).

Functions:

Name	Description
`build_equation`	Build a structural LaTeX equation from model containers.

Classes¶

Functions¶

build_equation¶

build_equation(spec: ModelSpec, bundle: DataBundle | None = None, formula_spec: FormulaSpec | None = None, *, explanations: bool = True) -> MathDisplay

Build a structural LaTeX equation from model containers.

Works in two modes:

Spec-only (no data): generic symbols from spec.fixed_terms.
With bundle: full rendering using bundle.X_names for exact column names, factor levels, contrast types, and transform parameters.

Parameters:

Name	Type	Description	Default
`spec`	`ModelSpec`	Model specification (always available).	required
`bundle`	`DataBundle \| None`	Data bundle (None before data is attached).	`None`
`formula_spec`	`FormulaSpec \| None`	Learned formula encoding (None before data is attached).	`None`
`explanations`	`bool`	Include term explanations in the output.	`True`

Returns:

Type	Description
`MathDisplay`	MathDisplay with equation, explanations, and rich display methods.

markdown¶

Markdown table and equation rendering for report export.

Pure functions that convert Polars DataFrames and LaTeX equations into pipe-delimited GitHub Flavored Markdown / Quarto-compatible text. Used by ModelResult.to_markdown(), MathDisplay.to_markdown(), and the top-level bossanova.to_markdown() utility.

Functions:

Name	Description
`dataframe_to_markdown`	Convert a Polars DataFrame to a pipe-delimited markdown table.
`equation_to_markdown`	Wrap a LaTeX equation in display math delimiters for Quarto.
`to_markdown`	Convert a Polars DataFrame to a markdown table, optionally saving to file.
`write_text`	Write text content to a file, creating parent directories.

Functions¶

dataframe_to_markdown¶

dataframe_to_markdown(df: pl.DataFrame, caption: str | None = None) -> str

Convert a Polars DataFrame to a pipe-delimited markdown table.

Produces GitHub Flavored Markdown (GFM) table syntax that renders correctly in Quarto, GitHub, and most markdown environments. Columns are padded to align visually. Null values render as empty cells.

No additional numeric formatting is applied — the DataFrame is assumed to be pre-rounded (as all bossanova result DataFrames are).

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Polars DataFrame to convert.	required
`caption`	`str \| None`	Optional table caption. Rendered as `Table: {caption}` above the table (Quarto cross-reference syntax).	`None`

Returns:

Type	Description
`str`	Pipe-delimited markdown table as a string.

Examples:

>>> import polars as pl
>>> df = pl.DataFrame({"x": [1, 2], "y": [3.14, 2.72]})
>>> print(dataframe_to_markdown(df))
| x | y    |
|---|------|
| 1 | 3.14 |
| 2 | 2.72 |

equation_to_markdown¶

equation_to_markdown(equation: str, explanations: tuple[str, ...] = (), *, include_explanations: bool = True) -> str

Wrap a LaTeX equation in display math delimiters for Quarto.

Produces $$...$$ display math that Quarto renders natively in Typst, HTML, and PDF output. Optionally appends term explanations as plain text below the equation block.

Parameters:

Name	Type	Description	Default
`equation`	`str`	LaTeX equation string (without `$$` delimiters).	required
`explanations`	`tuple[str, ...]`	Term explanation strings from `MathDisplay`.	`()`
`include_explanations`	`bool`	If True (default), append explanations as plain text lines below the equation.	`True`

Returns:

Type	Description
`str`	Markdown string with display math block and optional explanations.

Examples:

>>> print(equation_to_markdown(r"y = \beta_0 + \beta_1 x"))
$$
y = \beta_0 + \beta_1 x
$$

to_markdown¶

to_markdown(df: pl.DataFrame, path: str | Path | None = None, caption: str | None = None) -> str

Convert a Polars DataFrame to a markdown table, optionally saving to file.

Standalone utility for DataFrames not wrapped in ModelResult — such as results from compare(), model.jointtest(), model.vif(), model.to_odds_ratio(), etc.

For ModelResult objects (returned by .fit(), .infer(), etc.), use result.to_markdown() instead.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Polars DataFrame to convert.	required
`path`	`str \| Path \| None`	Optional file path. If given, writes the markdown and creates parent directories automatically.	`None`
`caption`	`str \| None`	Optional table caption (`Table: ...` Quarto syntax).	`None`

Returns:

Type	Description
`str`	Pipe-delimited markdown table as a string.

Examples:

>>> from bossanova import compare, to_markdown
>>> to_markdown(compare(m1, m2), "comparison.md", caption="Model Comparison")
>>> md = to_markdown(m.jointtest())  # string only

write_text¶

write_text(text: str, path: str | Path) -> None

Write text content to a file, creating parent directories.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Destination file path. Parent directories are created automatically if they don’t exist.	required
`text`	`str`	Text content to write.	required