pdstools.impactanalyzer¶

Submodules¶

Classes¶

ImpactAnalyzer

Analyze and visualize Impact Analyzer experiment results from Pega Customer Decision Hub.

Package Contents¶

class ImpactAnalyzer(raw_data: polars.LazyFrame)¶

Analyze and visualize Impact Analyzer experiment results from Pega Customer Decision Hub.

The ImpactAnalyzer class provides comprehensive 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.

When reading from PDC, the ImpactAnalyzer class only keeps the counts of impressions, accepts and the action value per impression and re-calculates all the derived values on demand. It drops inactive experiments and adds rows for the “NBA” group. The “All channels” is dropped. ValueLift and ValueLiftInterval are copied from the PDC data as this can currently not be re-calculated from the available raw numbers (ValuePerImpression is empty).

Engagement Lift is calculated as (SuccessRate(test) - SuccessRate(control))/SuccessRate(control)

Value Lift is calculated as (ValueCapture(test) - ValueCapture(control))/ValueCapture(control)

For value, aggregting the Value property

Parameters:: raw_data (polars.LazyFrame)

ia_data: polars.LazyFrame¶

default_ia_experiments¶

default_ia_controlgroups¶

plot¶

Create an ImpactAnalyzer instance from a PDC file

Parameters:

pdc_source (Union[os.PathLike, str, List[os.PathLike], List[str]]) – The full path to the PDC file, or a list of such paths
reader (Optional[Callable]) – Function to read the source data into a dict. If None uses standard file reader.
query (Optional[QUERY], optional) – An optional argument to filter out selected data, by default None
return_wide_df (Optional[QUERY], optional) – Debugging option to return the wide data from the raw JSON file as a LazyFrame, for debugging, by default False
return_df (Optional[QUERY], optional) – Returns the processed input data as a LazyFrame. Multiple of these can be stacked up and used to initialize the ImpactAnalyzer class, by default False

Returns:

The properly initialized ImpactAnalyzer object

Return type:

ImpactAnalyzer

classmethod from_vbd(vbd_source: os.PathLike | str | List[os.PathLike] | List[str], *, return_df: bool | None = False)¶

Abstractmethod:

Parameters:

vbd_source (Union[os.PathLike, str, List[os.PathLike], List[str]])
return_df (Optional[bool])

Create an ImpactAnalyzer instance from VBD (Value-Based Decisioning) data

This method will process VBD Actuals or VBD Scenario Planner Actuals data to reconstruct Impact Analyzer experiment metrics. This allows for more flexible time ranges and data selection compared to PDC exports.

IA uses pyReason, MktType, MktValue and ModelControlGroup to define the various experiments. For the standard NBA decisions (no experiment), values are left empty (null).

Prior to Impact Analyzer, or when turned off, Predictions from Prediction Studio manage two groups through the ModelControlGroup property. A value of Test is used for model driven arbitration, Control for the random control group (defaults to 2%).

When IA is on, the distinct values from just MktValue are sufficient to identify the different experiments. In the future, more and custom experiments may be supported.

For the full NBA interactions the value of the marker fields is left empty.

TODO: NBAHealth_ModelControl_2 is conceptually the same as NBAHealth_PropensityPriority and will be phased out in Pega 24.1/24.2.

The usage of “Default” issues and groups indicates that there is no action. These need to be filtered out for proper reporting.

TODO: should we exclude these from analysis?

TODO: what about things with inactive status? And how can we know?

NOTE: Impact Analyzer goes back from today’s date, also when the data is from an earlier date.

Parameters:

vbd_source (Union[os.PathLike, str, List[os.PathLike], List[str]]) – Path to VBD export file(s) or URL(s)
return_df (Optional[bool], optional) – Return processed data instead of ImpactAnalyzer instance, by default False

Returns:

The properly initialized ImpactAnalyzer object with reconstructed experiment data

Return type:

ImpactAnalyzer

Examples

>>> # Load from VBD export
>>> ia = ImpactAnalyzer.from_vbd('Data-pxStrategyResult_ActualsExport.zip')

Raises:

NotImplementedError – This method is not yet implemented. Use from_pdc() for current functionality.

Parameters:

vbd_source (Union[os.PathLike, str, List[os.PathLike], List[str]])
return_df (Optional[bool])

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

Internal method to turn PDC Impact Analyzer JSON data into a proper long format

The PDC data is really structured as a list of expriments: control group A vs control group B. There is no explicit indicator whether the B’s are really the same customers or not. The PDC data also contains a lot of UI related information that is not necessary.

We turn this data into a series of control groups with just counts of impressions and accepts. This does need to assume a few implicit assumptions.

Parameters:

json_data (dict)
query (Optional[pdstools.utils.types.QUERY])
return_wide_df (Optional[bool])

summary_by_channel() → polars.LazyFrame¶

Summarization of the experiments in Impact Analyzer split by Channel.

Returns:

Summary across all running Impact Analyzer experiments as a dataframe with the following fields:

Channel Identification: - Channel: The channel name

Performance Metrics: - CTR_Lift Adaptive Models vs Random Propensity: Lift in Engagement when testing prioritization with just Adaptive Models vs just Random Propensity - CTR_Lift NBA vs No Levers: Lift in Engagement for the full NBA Framework as configured vs prioritization without levers (only p, V and C) - CTR_Lift NBA vs Only Eligibility Rules: Lift in Engagement for the full NBA Framework as configured vs Only Eligibility policies applied (no Applicability or Suitability, and prioritized with pVCL) - CTR_Lift NBA vs Propensity Only: Lift in Engagement for the full NBA Framework as configured vs prioritization with model propensity only (no V, C or L) - CTR_Lift NBA vs Random: Lift in Engagement for the full NBA Framework as configured vs a Random eligible action (all engagement policies but randomly prioritized) - Value_Lift Adaptive Models vs Random Propensity: Lift in Expected Value when testing prioritization with just Adaptive Models vs just Random Propensity - Value_Lift NBA vs No Levers: Lift in Expected Value for the full NBA Framework as configured vs prioritization without levers (only p, V and C) - Value_Lift NBA vs Only Eligibility Rules: Lift in Expected Value for the full NBA Framework as configured vs Only Eligibility policies applied (no Applicability or Suitability, and prioritized with pVCL) - Value_Lift NBA vs Propensity Only: Lift in Expected Value for the full NBA Framework as configured vs prioritization with model propensity only (no V, C or L) - Value_Lift NBA vs Random: Lift in Expected Value for the full NBA Framework as configured vs a Random eligible action (all engagement policies but randomly prioritized)

Return type:

pl.LazyFrame

overall_summary() → polars.LazyFrame¶

Summarization of the experiments in Impact Analyzer.

Returns:

Summary across all running Impact Analyzer experiments as a dataframe with the following fields:

Return type:

pl.LazyFrame

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

Parameters:: by (Optional[Union[List[str], str]])
Return type:: polars.LazyFrame

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

Parameters:: by (Optional[Union[List[str], str]])
Return type:: polars.LazyFrame