Module trase.tools.sei_pcs.notebooks

Small display helpers shared by the SEI-PCS QA notebooks.

These were originally copy-pasted into each notebook under trase/products/analysis/notebooks/qa. They live here so that a notebook can from trase.tools.sei_pcs.notebooks import display_table(), show_s3_versions() instead of carrying its own copy.

Both helpers return IPython display objects, so call them from a notebook cell (display(show_s3_versions()(key))) rather than from library code.

Functions

def display_table(df,
headers: Dict[str, str] | None = None,
formats: Dict[str, str | Callable] | None = None,
number_format: str | None = None,
number_align: str = 'right',
string_align: str = 'left')

Render a Polars DataFrame as a clean Markdown table via tabulate.

Args

df

the Polars DataFrame to display.

headers : optional

{column: label} overrides for the column headers. Columns not listed fall back to the column name with underscores turned into spaces and the first letter capitalised.

formats : optional

{column: spec}, where spec is either a Python format spec applied as format(value, spec) (e.g. ".2f" for two decimals, ".2g" for two significant figures, ",.0f" for a thousands-separated integer) or a callable value -> str.

number_format : optional

format spec applied to any numeric column not named in formats. Default: leave the value as-is.

number_align / string_align (optional): column alignment for numeric / other columns. Default: numbers right, strings left. Returns: an IPython Markdown object that renders as a GitHub-flavoured table.

def show_s3_versions(*keys: str, bucket: str | None = None)

Record exactly which S3 objects feed a notebook.

For each key, HEAD the object and display its version ID and last-modified date alongside its path, before it is loaded, so the provenance of the data is baked into the rendered notebook output.

Args

*keys

S3 object keys, relative to the bucket.

bucket : optional

the bucket to read from. Default: settings.bucket.

Returns: an IPython Markdown object rendering as a table.

def significant_figures(digits: int = 3) ‑> Callable[[float], str]

Return a display_table() formatter: comma-grouped, rounded to digits.

Reporting a whole tonnage to eight digits implies a precision a supply-chain model does not have, so large quantities are rounded for display while keeping the thousands separators that make the magnitude readable: 17546961 prints as 17,500,000.

Use it as display_table(df, number_format=significant_figures()) to apply it to every numeric column, or per column through formats.