pdstools.utils.report_utils._tables

RAG-coloured metric table builders (itables and great_tables).

Functions

create_metric_itable(source_table[, column_to_metric, ...])

Create an interactive table with RAG coloring for metric columns.

create_metric_gttable(source_table[, title, subtitle, ...])

Create a great_tables table with RAG coloring for metric columns.

Module Contents

create_metric_itable(source_table: polars.DataFrame, column_to_metric: dict | None = None, column_descriptions: dict[str, str] | None = None, color_background: bool = False, strict_metric_validation: bool = True, highlight_issues_only: bool = False, rag_source: polars.DataFrame | None = None, **itable_kwargs)

Create an interactive table with RAG coloring for metric columns.

Displays the table using itables with cells colored based on RAG (Red/Amber/Green) status derived from metric thresholds.

Parameters:

  • source_table (pl.DataFrame) – DataFrame containing data columns to be colored.

  • column_to_metric (dict, optional) –

    Mapping from column names (or tuples of column names) to one of:

    • str: metric ID to look up in MetricLimits.csv

    • callable: function(value) -> “RED”|”AMBER”|”YELLOW”|”GREEN”|None

    • tuple: (metric_id, value_mapping) where value_mapping is a dict that maps column values to metric values before evaluation. Supports tuple keys for multiple values: {(“Yes”, “yes”): True}

    If a column is not in this dict, its name is used as the metric ID.

  • column_descriptions (dict, optional) – Mapping from column names to tooltip descriptions. When provided, column headers will display the description as a tooltip on hover. Example: {“Performance”: “Model AUC performance metric”}

  • color_background (bool, default False) – If True, colors the cell background. If False, colors the text (foreground).

  • strict_metric_validation (bool, default True) – If True, raises an exception if a metric ID in column_to_metric is not found in MetricLimits.csv. Set to False to skip validation.

  • highlight_issues_only (bool, default False) – If True, only RED/AMBER/YELLOW values are styled (GREEN is not highlighted). Set to False to also highlight GREEN values.

  • rag_source (pl.DataFrame, optional) – If provided, RAG thresholds are evaluated against this DataFrame instead of source_table. Use this when source_table contains non-numeric display values (e.g. HTML strings) but you still want RAG coloring based on the original numeric data. Must have the same columns and row order as source_table.

  • **itable_kwargs – Additional keyword arguments passed to itables.show(). Common options include: lengthMenu, paging, searching, ordering.

Returns:

An itables display object that will render in Jupyter/Quarto.

Return type:

itables HTML display

Examples

>>> from pdstools.utils.report_utils import create_metric_itable
>>> create_metric_itable(
...     df,
...     column_to_metric={
...         # Simple metric ID
...         "Performance": "ModelPerformance",
...         # Custom RAG function
...         "Channel": standard_NBAD_channels_rag,
...         # Value mapping: column values -> metric values
...         "AGB": ("UsingAGB", {"Yes": True, "No": False}),
...         # Multiple column values to same metric value
...         "AGB": ("UsingAGB", {("Yes", "yes", "YES"): True, "No": False}),
...     },
...     column_descriptions={
...         "Performance": "Model AUC performance metric",
...         "Channel": "Communication channel for the action",
...     },
...     paging=False
... )
create_metric_gttable(source_table: polars.DataFrame, title: str | None = None, subtitle: str | None = None, column_to_metric: dict | None = None, column_descriptions: dict[str, str] | None = None, color_background: bool = True, strict_metric_validation: bool = True, highlight_issues_only: bool = True, **gt_kwargs)

Create a great_tables table with RAG coloring for metric columns.

Displays the table using great_tables with cells colored based on RAG (Red/Amber/Green) status derived from metric thresholds.

Parameters:

  • source_table (pl.DataFrame) – DataFrame containing data columns to be colored.

  • title (str, optional) – Table title.

  • subtitle (str, optional) – Table subtitle.

  • column_to_metric (dict, optional) –

    Mapping from column names (or tuples of column names) to one of:

    • str: metric ID to look up in MetricLimits.csv

    • callable: function(value) -> “RED”|”AMBER”|”YELLOW”|”GREEN”|None

    • tuple: (metric_id, value_mapping) where value_mapping is a dict that maps column values to metric values before evaluation. Supports tuple keys for multiple values: {(“Yes”, “yes”): True}

    If a column is not in this dict, its name is used as the metric ID.

  • column_descriptions (dict, optional) – Mapping from column names to tooltip descriptions. When provided, column headers will display the description as a tooltip on hover. Example: {“Performance”: “Model AUC performance metric”}

  • color_background (bool, default True) – If True, colors the cell background. If False, colors the text.

  • strict_metric_validation (bool, default True) – If True, raises an exception if a metric ID in column_to_metric is not found in MetricLimits.csv. Set to False to skip validation.

  • highlight_issues_only (bool, default True) – If True, only RED/AMBER/YELLOW values are styled (GREEN is not highlighted). Set to False to also highlight GREEN values.

  • **gt_kwargs – Additional keyword arguments passed to great_tables.GT constructor. Common options include: rowname_col, groupname_col.

Returns:

A great_tables instance with RAG coloring applied.

Return type:

great_tables.GT

Examples

>>> from pdstools.utils.report_utils import create_metric_gttable
>>> create_metric_gttable(
...     df,
...     title="Model Overview",
...     column_to_metric={
...         # Simple metric ID
...         "Performance": "ModelPerformance",
...         # Custom RAG function
...         "Channel": standard_NBAD_channels_rag,
...         # Value mapping: column values -> metric values
...         "AGB": ("UsingAGB", {"Yes": True, "No": False}),
...         # Multiple column values to same metric value
...         "AGB": ("UsingAGB", {("Yes", "yes", "YES"): True, "No": False}),
...     },
...     column_descriptions={
...         "Performance": "Model AUC performance metric",
...         "Channel": "Communication channel for the action",
...     },
...     rowname_col="Name",
... )