pdstools.decision_analyzer¶

Submodules¶

Classes¶

DecisionAnalyzer

Analyze NBA decision data from Explainability Extract or Decision Analyzer exports.

Package Contents¶

class DecisionAnalyzer(raw_data: polars.LazyFrame, *, level: str = 'Stage Group', sample_size: int = DEFAULT_SAMPLE_SIZE, mandatory_expr: polars.Expr | None = None, additional_columns: dict[str, polars.DataType] | None = None, num_samples: int = 1)¶

Analyze NBA decision data from Explainability Extract or Decision Analyzer exports.

This class processes raw decision data to create a comprehensive analysis framework for NBA (Next-Best-Action). It supports two data source formats:

Explainability Extract (v1): Simpler format with actions at the arbitration stage. Stages are synthetically derived from ranking.
Decision Analyzer / EEV2 (v2): Full pipeline data with real stage information, filter component names, and detailed strategy tracking.

Data can be loaded via class methods or directly:

from_explainability_extract(): Load from an Explainability Extract file.
from_decision_analyzer(): Load from a Decision Analyzer (EEV2) file.
Direct __init__: Auto-detects format from the data schema.

Parameters:

raw_data (polars.LazyFrame)
level (str)
sample_size (int)
mandatory_expr (polars.Expr | None)
additional_columns (dict[str, polars.DataType] | None)
num_samples (int)

decision_data¶

Interaction-level decision data (with global filters applied if any).

Type:: pl.LazyFrame

extract_type¶

Either "explainability_extract" or "decision_analyzer".

Type:: str

plot¶

Plot accessor for visualization methods.

Type:: Plot

aggregates¶

Accessor for aggregation queries (funnel, distribution, optionality, action variation, …).

Type:: Aggregates

scoring¶

Accessor for re-ranking, sensitivity, win/loss and lever analysis.

Type:: Scoring

Examples

>>> from pdstools import DecisionAnalyzer
>>> da = DecisionAnalyzer.from_explainability_extract("data/sample_explainability_extract.parquet")
>>> da.overview_stats
>>> da.plot.sensitivity()
>>> da.aggregates.get_funnel_data(scope="Action")
>>> da.scoring.get_sensitivity()

_num_sample_interactions: int¶

classmethod from_explainability_extract(source: str | os.PathLike, *, level: str = 'Stage Group', sample_size: int = DEFAULT_SAMPLE_SIZE, mandatory_expr: polars.Expr | None = None, additional_columns: dict[str, polars.DataType] | None = None, num_samples: int = 1) → DecisionAnalyzer¶

Create a DecisionAnalyzer from an Explainability Extract (v1) file.

Parameters:

source (str | os.PathLike) – Path to the Explainability Extract parquet file, or a URL.
level (str) – See __init__() for details.
sample_size (int) – See __init__() for details.
mandatory_expr (polars.Expr | None) – See __init__() for details.
additional_columns (dict[str, polars.DataType] | None) – See __init__() for details.
num_samples (int) – See __init__() for details.

Return type:

DecisionAnalyzer

Examples

>>> da = DecisionAnalyzer.from_explainability_extract("data/sample_explainability_extract.parquet")

classmethod from_decision_analyzer(source: str | os.PathLike, *, level: str = 'Stage Group', sample_size: int = DEFAULT_SAMPLE_SIZE, mandatory_expr: polars.Expr | None = None, additional_columns: dict[str, polars.DataType] | None = None, num_samples: int = 1) → DecisionAnalyzer¶

Create a DecisionAnalyzer from a Decision Analyzer / EEV2 (v2) file.

Parameters:

source (str | os.PathLike) – Path to the Decision Analyzer parquet file, or a URL.
level (str) – See __init__() for details.
sample_size (int) – See __init__() for details.
mandatory_expr (polars.Expr | None) – See __init__() for details.
additional_columns (dict[str, polars.DataType] | None) – See __init__() for details.
num_samples (int) – See __init__() for details.

Return type:

DecisionAnalyzer

Examples

>>> da = DecisionAnalyzer.from_decision_analyzer("data/sample_eev2.parquet")

_default_filter_fields = ['Decision Time', 'Channel', 'Direction', 'Issue', 'Group', 'Action', 'Treatment', 'Stage',...¶

plot¶

aggregates¶

scoring¶

level = 'Stage Group'¶

sample_size = 10000¶

_num_samples = 1¶

_thresholding_cache: dict[tuple[str, tuple[int, Ellipsis]], polars.DataFrame]¶

_sensitivity_cache: dict[int, polars.LazyFrame]¶

extract_type = 'decision_analyzer'¶

validation_error = 'The following default columns are missing: '¶

decision_data¶

fields_for_data_filtering¶

preaggregation_columns¶

max_win_rank = 5¶

AvailableNBADStages = ['Arbitration', 'Output']¶

property available_levels: list[str]¶

Stage granularity levels available for this dataset.

Returns ["Stage Group", "Stage"] for Decision Analyzer (v2) data when both columns are present, or ["Stage Group"] for Explainability Extract (v1) data where only synthetic stages exist.

Return type:: list[str]

set_level(level: str)¶

Switch the stage granularity level used for all analyses.

Recomputes the available stages for the new level and invalidates all cached properties so subsequent queries use the new granularity.

Parameters:: level (str) – "Stage Group" or "Stage".

_recompute_available_stages()¶

Derive AvailableNBADStages from the data for the current level.

At “Stage Group” level, synthetically injects “Arbitration” if it has no data rows (it is used as an anchor point by many analyses).

At “Stage” level, detects Stage Groups that have no individual stages represented in the data and inserts the group name as a placeholder so the full pipeline is visible.

property mandatory_actions: set[str]¶

Set of action names flagged as mandatory in the current data.

Mandatory actions bypass normal arbitration and always rank in the top slot. Auto-detected from Priority (see MANDATORY_PRIORITY_THRESHOLD) unless an explicit mandatory_expr was supplied at construction.

Returns:: Distinct Action values where is_mandatory is truthy. Empty when no mandatory rows or no Action / is_mandatory column is available.
Return type:: set[str]

property color_mappings: dict[str, dict[str, str]]¶

Compute consistent color mappings for all categorical dimensions.

Color assignments are based on all unique values in the full dataset (before sampling), sorted alphabetically. This ensures colors remain consistent throughout the session regardless of filtering.

Returns:

Nested dictionary mapping dimension names to color dictionaries. Example: {

”Issue”: {“Retention”: “#001F5F”, “Sales”: “#10A5AC”}, “Group”: {“CreditCards”: “#001F5F”, “Loans”: “#10A5AC”},

}

Return type:

dict[str, dict[str, str]]

Notes

Uses @cached_property so computation happens once on first access. Colors are assigned from the Pega colorway using modulo indexing.