pdstools.explanations.Explanations

Classes

Explanations

Process and explore explanation data for Adaptive Gradient Boost models.

Module Contents

class Explanations(overall: polars.LazyFrame, contextual: polars.LazyFrame, *, model_name: str | None = None, from_date: datetime.datetime | None = None, to_date: datetime.datetime | None = None)

Process and explore explanation data for Adaptive Gradient Boost models.

The class is a thin orchestrator over three sub-namespaces (aggregates, plot, report) that operate on pre-aggregated parquet files.

The constructor is pure configuration — it accepts already-scanned polars.LazyFrame`s and path settings, and performs no I/O. Use :meth:`from_aggregates to read the parquet files from disk.

Parameters:

  • overall (pl.LazyFrame) – Contributions aggregated across all contexts.

  • contextual (pl.LazyFrame) – Contributions aggregated per context.

  • model_name (str, optional) – Name of the model rule. Used for report metadata only.

  • from_date (datetime, optional) – Start date of the period over which aggregates are computed. Defaults to to_date - 7 days if only to_date is given, or to today() - 7 days if both are omitted.

  • to_date (datetime, optional) – End date of the period over which aggregates are computed. Defaults to today() if only from_date is given, or to today() if both are omitted.

See also

Explanations.from_aggregates

Load pre-aggregated parquet files.

Notes

Environment variables that influence the batch parquet file generation:

PDSTOOLS_FILE_BATCH_LIMIT

Number of context partitions per batch. Default: 100.

Examples

Load pre-aggregated explanation data:

>>> from pathlib import Path
>>> exp = Explanations.from_aggregates(
...     base_path=Path(".tmp/aggregated_data"),
...     model_name="AdaptiveBoostCT",
...     from_date=datetime(2025, 3, 28),
...     to_date=datetime(2025, 3, 28),
... )
>>> df = exp.overall.collect()

Construct with a custom aggregates path:

>>> exp = Explanations.from_aggregates(base_path="/path/to/my/aggregates")
>>> df = exp.overall.collect()

The aggregates may also live behind a URL:

>>> exp = Explanations.from_aggregates(base_path="https://example.com/aggregates")
>>> df = exp.overall.collect()
overall: polars.LazyFrame

Contributions aggregated across all contexts.

contextual: polars.LazyFrame

Contributions aggregated per context.

model_name = None
aggregates
plot
report
classmethod from_aggregates(overall_filename: str | pathlib.Path = 'OVERVIEW.parquet', contextual_filename: str | pathlib.Path = 'BY_CONTEXT.parquet', base_path: str | pathlib.Path = '.', *, model_name: str | None = None, from_date: datetime.datetime | None = None, to_date: datetime.datetime | None = None) → Explanations

Construct an Explanations from pre-aggregated parquet files.

This is the standard entry point: it points to a folder containing pre-aggregated parquet files and returns a ready-to-query instance.

Parameters:

  • overall_filename (str | Path, default "OVERVIEW.parquet") – Contributions aggregated across all contexts, relative to base_path. A full path is used as-is, ignoring base_path.

  • contextual_filename (str | Path, default "BY_CONTEXT.parquet") – Contributions aggregated per context, relative to base_path. A full path is used as-is, ignoring base_path. The report pipeline uses this to point a page at a single pre-computed batch (e.g. "batches/BATCH_3.parquet") instead of the full set.

  • base_path (str | Path, default ".") – Folder containing the pre-aggregated parquet files. May be an http(s):// URL.

  • model_name (str, optional) – Name of the model rule. Used for report metadata only.

  • from_date (datetime, optional) – Start date of the period over which aggregates are computed. See Explanations for default behaviour.

  • to_date (datetime, optional) – End date of the period over which aggregates are computed. See Explanations for default behaviour.

Returns:

A fully initialised instance holding LazyFrames over the aggregated data.

Return type:

Explanations

Raises:

FileNotFoundError – If either aggregate file does not exist.

save_data(path: str | pathlib.Path = '.') → tuple[pathlib.Path, pathlib.Path]

Cache overall and contextual to parquet files.

Mirrors ADMDatamart.save_data(). The report pipeline uses this to materialise the frames into its working directory, so that the Quarto subprocess reads local files regardless of where the data came from - a URL, a database, or frames built in memory.

Parameters:

path (str | Path, default ".") – Directory to write into. Created if it does not exist.

Returns:

Paths of the written overall and contextual parquet files.

Return type:

tuple[Path, Path]