pdstools.impactanalyzer.ImpactAnalyzer¶

Classes¶

ImpactAnalyzer

Analyze and visualize Impact Analyzer experiment results from Pega CDH.

Module Contents¶

class ImpactAnalyzer(raw_data: polars.LazyFrame)¶

Analyze and visualize Impact Analyzer experiment results from Pega CDH.

The ImpactAnalyzer class provides analysis and visualization capabilities for NBA (Next-Best-Action) Impact Analyzer experiments. It processes experiment data from Pega’s Customer Decision Hub to compare the effectiveness of different NBA strategies including adaptive models, propensity prioritization, lever usage, and engagement policies.

Data can be loaded from three sources:

PDC exports via from_pdc(): Uses pre-aggregated experiment data from PDC JSON exports. Value Lift is copied from PDC data as it cannot be re-calculated from the available numbers.
VBD exports via from_vbd(): Reconstructs experiment metrics from raw VBD Actuals or Scenario Planner Actuals data. Allows flexible time ranges and data selection. Value Lift is calculated from ValuePerImpression.
Interaction History via from_ih(): Loads experiment metrics from Interaction History data. Not yet implemented.

\[\text{Engagement Lift} = \frac{\text{SuccessRate}_{test} - \text{SuccessRate}_{control}}{\text{SuccessRate}_{control}}\]

\[\text{Value Lift} = \frac{\text{ValueCapture}_{test} - \text{ValueCapture}_{control}}{\text{ValueCapture}_{control}}\]

Parameters:: raw_data (polars.LazyFrame)

ia_data¶

The underlying experiment data containing control group metrics.

Type:: pl.LazyFrame

plot¶

Plot accessor for visualization methods.

Type:: Plots

See also

pdstools.adm.ADMDatamart: For ADM model analysis.
pdstools.ih.IH: For Interaction History analysis.

Examples

>>> from pdstools import ImpactAnalyzer
>>> ia = ImpactAnalyzer.from_pdc("impact_analyzer_export.json")
>>> ia.overall_summary().collect()
>>> ia.plot.overview()

ia_data: polars.LazyFrame¶

default_ia_experiments¶: Default experiments mapping experiment names to (control, test) group tuples.

outcome_labels¶: Mapping of metric names to outcome labels used for aggregation.

default_ia_controlgroups¶

plot¶

Create an ImpactAnalyzer instance from PDC JSON export(s).

Loads pre-aggregated experiment data from Pega Decision Central JSON exports. Value Lift metrics are copied directly from the PDC data.

Parameters:

pdc_source (Union[os.PathLike, str, List[os.PathLike], List[str]]) – Path to PDC JSON file, or a list of paths to concatenate.
reader (Optional[Callable], optional) – Custom function to read source data into a dict. If None, uses standard JSON file reader. Default is None.
query (Optional[QUERY], optional) – Polars expression to filter the data. Default is None.
return_wide_df (bool, optional) – If True, return the raw wide-format data as a LazyFrame for debugging. Default is False.
return_df (bool, optional) – If True, return the processed data as a LazyFrame instead of an ImpactAnalyzer instance. Default is False.

Returns:

ImpactAnalyzer instance, or LazyFrame if return_df or return_wide_df is True.

Return type:

ImpactAnalyzer or pl.LazyFrame

Raises:

ValueError – If an empty list of source files is provided.

Examples

>>> ia = ImpactAnalyzer.from_pdc("CDH_Metrics_ImpactAnalyzer.json")
>>> ia.overall_summary().collect()

classmethod from_vbd(vbd_source: os.PathLike | str, *, return_df: bool = False) → ImpactAnalyzer | polars.LazyFrame | None¶

Create an ImpactAnalyzer instance from VBD data.

Processes VBD Actuals or Scenario Planner Actuals data to reconstruct Impact Analyzer experiment metrics. Provides more flexible time ranges and data selection compared to PDC exports.

Value Lift is calculated from ValuePerImpression since raw value data is available in VBD exports.

Parameters:

vbd_source (Union[os.PathLike, str]) – Path to VBD export file (parquet, csv, ndjson, or zip).
return_df (bool, optional) – If True, return processed data as LazyFrame instead of ImpactAnalyzer instance. Default is False.

Returns:

ImpactAnalyzer instance, LazyFrame if return_df is True, or None if the source contains no data.

Return type:

ImpactAnalyzer or pl.LazyFrame or None

Examples

>>> ia = ImpactAnalyzer.from_vbd("ScenarioPlannerActuals.zip")
>>> ia.summary_by_channel().collect()

classmethod from_ih(ih_source: os.PathLike | str, *, return_df: bool = False) → ImpactAnalyzer | polars.LazyFrame | None¶

Abstractmethod:

Parameters:

ih_source (Union[os.PathLike, str])
return_df (bool)

Return type:

Union[ImpactAnalyzer, polars.LazyFrame, None]

Create an ImpactAnalyzer instance from Interaction History data.

Note

This method is not yet implemented.

Reconstructs experiment metrics from Interaction History data, allowing analysis of experiments using detailed interaction-level records.

Parameters:

ih_source (Union[os.PathLike, str]) – Path to Interaction History export file.
return_df (bool, optional) – If True, return processed data as LazyFrame instead of ImpactAnalyzer instance. Default is False.

Returns:

ImpactAnalyzer instance, LazyFrame if return_df is True, or None if the source contains no data.

Return type:

ImpactAnalyzer or pl.LazyFrame or None

Raises:

NotImplementedError – This method is not yet implemented.

classmethod _normalize_pdc_ia_data(json_data: dict, *, query: pdstools.utils.types.QUERY | None = None, return_wide_df: bool = False) → polars.LazyFrame¶

Transform PDC Impact Analyzer JSON into normalized long format.

Converts the hierarchical PDC JSON structure (organized by experiments) into a flat structure organized by control groups with impression and accept counts.

Parameters:

json_data (dict) – Parsed JSON data from PDC export.
query (Optional[QUERY], optional) – Polars expression to filter the data. Default is None.
return_wide_df (bool, optional) – If True, return intermediate wide-format data. Default is False.

Returns:

Normalized data with columns: SnapshotTime, Channel, ControlGroup, Impressions, Accepts, ValuePerImpression, Pega_ValueLift.

Return type:

pl.LazyFrame

summary_by_channel() → polars.LazyFrame¶

Get experiment summary pivoted by channel.

Returns experiment lift metrics (CTR_Lift and Value_Lift) for each experiment, with one row per channel.

Returns:

Wide-format summary with columns:

Channel: Channel name
CTR_Lift <Experiment>: Engagement lift for each experiment
Value_Lift <Experiment>: Value lift for each experiment

Return type:

pl.LazyFrame

See also

overall_summary: Summary without channel breakdown.
summarize_experiments: Long-format experiment summary.

Examples

>>> ia.summary_by_channel().collect()

overall_summary() → polars.LazyFrame¶

Get overall experiment summary aggregated across all channels.

Returns experiment lift metrics (CTR_Lift and Value_Lift) for each experiment, aggregated across all data.

Returns:

Single-row wide-format summary with columns:

CTR_Lift <Experiment>: Engagement lift for each experiment
Value_Lift <Experiment>: Value lift for each experiment

Return type:

pl.LazyFrame

See also

summary_by_channel: Summary with channel breakdown.
summarize_experiments: Long-format experiment summary.

Examples

>>> ia.overall_summary().collect()

summarize_control_groups(by: List[str] | List[polars.Expr] | str | polars.Expr | None = None, drop_internal_cols: bool = True) → polars.LazyFrame¶

Aggregate metrics by control group.

Summarizes impressions, accepts, CTR, and value metrics for each control group, optionally grouped by additional dimensions.

Parameters:

by (Optional[Union[List[str], List[pl.Expr], str, pl.Expr]], optional) – Column name(s) or expression(s) to group by in addition to ControlGroup. Default is None (aggregate all data).
drop_internal_cols (bool, optional) – If True, drop internal columns prefixed with ‘Pega_’. Default is True.

Returns:

Aggregated metrics with columns: ControlGroup, Impressions, Accepts, CTR, ValuePerImpression, plus any grouping columns.

Return type:

pl.LazyFrame

Examples

>>> ia.summarize_control_groups().collect()
>>> ia.summarize_control_groups(by="Channel").collect()

summarize_experiments(by: List[str] | List[polars.Expr] | str | polars.Expr | None = None) → polars.LazyFrame¶

Summarize experiment metrics comparing test vs control groups.

Computes lift metrics for each defined experiment by comparing test and control group performance.

Note

Returns all default experiments regardless of whether they are active in the data. Experiments without data will have null values for all metrics (Impressions, Accepts, CTR_Lift, Value_Lift, etc.).

Parameters:

by (Optional[Union[List[str], List[pl.Expr], str, pl.Expr]], optional) – Column name(s) or expression(s) to group by. Default is None (aggregate all data).

Returns:

Experiment summary with columns:

Experiment: Experiment name
Test, Control: Control group names for the experiment
Impressions_Test, Impressions_Control: Impression counts (null if not active)
Accepts_Test, Accepts_Control: Accept counts (null if not active)
CTR_Test, CTR_Control: Click-through rates (null if not active)
Control_Fraction: Fraction of impressions in control group
CTR_Lift: Engagement lift (null if experiment not active)
Value_Lift: Value lift (null if experiment not active)

Return type:

pl.LazyFrame

See also

summarize_control_groups: Lower-level control group aggregation.
overall_summary: Pivoted overall summary.
summary_by_channel: Pivoted summary by channel.

Examples

>>> ia.summarize_experiments().collect()
>>> ia.summarize_experiments(by="Channel").collect()