Skip to content

format_paper_summary

format_paper_summary

format_paper_summary(profile: Series | DataFrame, *, fmt: str = 'markdown', decimals: int = 2) -> str

Render a profile as a publication-ready Markdown or LaTeX table.

Every paper carries a "Table 1: dataset description". Turning the raw output of system_profile or compare_systems into a clean table (rounded floats, thousands separators, aligned columns) is a recurring twenty-minute chore. This does it in one call. It only formats your own profiling output; it computes nothing new.

Parameters:

Name Type Description Default
profile Series or DataFrame

A profile, e.g. from system_profile (Series) or compare_systems (DataFrame).

required
fmt ('markdown', 'latex')

Output dialect. "latex" delegates to to_latex.

"markdown"
decimals int

Rounding for floating-point cells (thousands separators are added in Markdown).

2

Returns:

Type Description
str

The formatted table, ready to paste into a manuscript.

See Also

system_profile : The single-system profile to format. compare_systems : The multi-system table to format.

Examples:

>>> import pandas as pd
>>> prof = pd.Series({"n_stations": 100, "mean_occupancy": 0.4123})
>>> out = format_paper_summary(prof)
>>> "mean_occupancy" in out and "0.41" in out
True
Source code in src/gbfs_toolkit/analytics/distribution.py
def format_paper_summary(
    profile: pd.Series | pd.DataFrame, *, fmt: str = "markdown", decimals: int = 2
) -> str:
    """Render a profile as a publication-ready Markdown or LaTeX table.

    Every paper carries a "Table 1: dataset description". Turning the raw output of
    [`system_profile`][gbfs_toolkit.system_profile] or [`compare_systems`][gbfs_toolkit.compare_systems] into a clean table (rounded floats,
    thousands separators, aligned columns) is a recurring twenty-minute chore. This does
    it in one call. It only formats your own profiling output; it computes nothing new.

    Parameters
    ----------
    profile : pandas.Series or pandas.DataFrame
        A profile, e.g. from [`system_profile`][gbfs_toolkit.system_profile] (Series) or [`compare_systems`][gbfs_toolkit.compare_systems]
        (DataFrame).
    fmt : {"markdown", "latex"}, default "markdown"
        Output dialect. ``"latex"`` delegates to `to_latex`.
    decimals : int, default 2
        Rounding for floating-point cells (thousands separators are added in Markdown).

    Returns
    -------
    str
        The formatted table, ready to paste into a manuscript.

    See Also
    --------
    [`system_profile`][gbfs_toolkit.system_profile] : The single-system profile to format.
    [`compare_systems`][gbfs_toolkit.compare_systems] : The multi-system table to format.

    Examples
    --------
    >>> import pandas as pd
    >>> prof = pd.Series({"n_stations": 100, "mean_occupancy": 0.4123})
    >>> out = format_paper_summary(prof)
    >>> "mean_occupancy" in out and "0.41" in out
    True
    """
    if fmt not in ("markdown", "latex"):
        raise ValueError(f"fmt must be 'markdown' or 'latex', got {fmt!r}")
    obj = profile.to_frame(name="value") if isinstance(profile, pd.Series) else profile.copy()
    obj = obj.round(decimals)

    def _cell(v: object) -> str:
        if isinstance(v, (int, float, np.floating)) and pd.notna(v):
            return f"{v:,.{decimals}f}"
        return str(v)

    header = [str(obj.index.name or ""), *[str(c) for c in obj.columns]]
    body = [[str(idx), *[_cell(v) for v in row]] for idx, row in obj.iterrows()]

    if fmt == "markdown":
        lines = [
            "| " + " | ".join(header) + " |",
            "| " + " | ".join("---" for _ in header) + " |",
            *["| " + " | ".join(r) + " |" for r in body],
        ]
        return "\n".join(lines)

    # LaTeX booktabs table, generated directly so no jinja2 / Styler dependency is needed.
    def _tex(s: str) -> str:
        return (
            s.replace("\\", "\\textbackslash{}")
            .replace("_", r"\_")
            .replace("%", r"\%")
            .replace("&", r"\&")
        )

    align = "l" + "r" * len(obj.columns)
    lines = [
        rf"\begin{{tabular}}{{{align}}}",
        r"\toprule",
        " & ".join(_tex(h) for h in header) + r" \\",
        r"\midrule",
        *[" & ".join(_tex(c) for c in r) + r" \\" for r in body],
        r"\bottomrule",
        r"\end{tabular}",
    ]
    return "\n".join(lines)