pdstools.explanations.ContextOperations¶

Context-related operations for querying the unique contexts in an aggregates set.

Classes¶

ContextOperations

Context-related operations for querying unique contexts.

Module Contents¶

class ContextOperations(explanations: pdstools.explanations.Explanations.Explanations)¶

Bases: pdstools.utils.namespaces.LazyNamespace

Context-related operations for querying unique contexts.

Parameters:: explanations (Explanations) – Parent instance providing the contextual data.

dependencies: ClassVar[list[str]] = ['polars']¶

dependency_group = 'explanations'¶

explanations¶

file_batch_limit¶

property context_keys: list[str]¶

Context key column names, for example ["pyChannel", "pyDirection"].

Return type:: list[str]

get_df(context_infos: list[dict[str, str]] | None = None, with_partition_col: bool = False) → polars.DataFrame¶

Return unique contexts as a DataFrame, optionally filtered.

Parameters:

context_infos (list[dict[str, str]] | None, default None) – Optional context filters. When provided, rows are filtered to the matching contexts.
with_partition_col (bool, default False) – Whether to include the raw context_partition column in the output.

Returns:

Unique contexts with one row per context.

Return type:

pl.DataFrame

get_list(context_infos: list[dict[str, str]] | None = None, with_partition_col: bool = False) → list[dict[str, str]]¶

Return unique contexts as dictionaries, optionally filtered.

Parameters:

context_infos (list[dict[str, str]] | None, default None) – Optional context filters. When provided, rows are filtered to the matching contexts.
with_partition_col (bool, default False) – Whether to include the raw context_partition field in each dictionary.

Returns:

Unique contexts represented as dictionaries.

Return type:

list[dict[str, str]]

write_batches(target_dir: str | pathlib.Path) → None¶

Write the per-batch parquet files and the context-to-batch mapping.

The report renders one page per batch, so contexts are chunked into groups of file_batch_limit. Both artifacts come out of the same assignment and cannot disagree: unique_contexts.json tells the report subprocess which contexts belong on which page, and each batches/BATCH_<n>.parquet holds exactly that page’s rows.

Nothing is cached — the files are rewritten on every call, so a change of dataset or of PDSTOOLS_FILE_BATCH_LIMIT takes effect.

Parameters:: target_dir (str | Path) – Directory to write unique_contexts.json and batches/ into.
Return type:: None

static get_context_info_str(context_info: dict[str, str], sep: str = '-') → str¶

Format a context dictionary into a compact string.

Parameters:

context_info (dict[str, str]) – Context dictionary to format.
sep (str, default "-") – Separator inserted between values.

Returns:

String containing context values joined by sep.

Return type:

str