pdstools.prediction.Prediction¶

Attributes¶

`logger`
`COLORSCALE_TYPES`
`Figure`

Classes¶

`PredictionPlots`	Plots for visualizing Prediction Studio data.
`Prediction`	Monitor and analyze Pega Prediction Studio Predictions.

Module Contents¶

logger¶

COLORSCALE_TYPES¶

Figure¶

class PredictionPlots(prediction)¶

Bases: pdstools.utils.namespaces.LazyNamespace

Plots for visualizing Prediction Studio data.

This class provides various plotting methods to visualize prediction performance, lift, CTR, and response counts over time.

dependencies = ['plotly']¶

prediction¶

_prediction_trend(period: str, query: pdstools.utils.types.QUERY | None, metric: str, title: str, **kwargs)¶

Internal method to create trend plots for various metrics.

Parameters:

period (str) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”)
query (Optional[QUERY]) – Optional query to filter the data
metric (str) – The metric to plot (e.g., “Performance”, “Lift”, “CTR”)
title (str) – Plot title
**kwargs – Additional keyword arguments passed directly to plotly.express.line See plotly.express.line documentation for all available options

Returns:

(plotly figure, dataframe with plot data)

Return type:

tuple

performance_trend(period: str = '1d', *, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False, **kwargs)¶

Create a performance trend plot showing AUC over time.

Parameters:

period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”
query (Optional[QUERY], optional) – Optional query to filter the data, by default None
return_df (bool, optional) – If True, returns the dataframe used for plotting instead of the plot, by default False
**kwargs – Additional keyword arguments passed directly to plotly.express.line See plotly.express.line documentation for all available options

Returns:

Either a plotly figure or the dataframe used for plotting if return_df is True

Return type:

Union[Figure, pl.DataFrame]

lift_trend(period: str = '1d', *, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False, **kwargs)¶

Create a lift trend plot showing engagement lift over time.

Parameters:

period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”
query (Optional[QUERY], optional) – Optional query to filter the data, by default None
return_df (bool, optional) – If True, returns the dataframe used for plotting instead of the plot, by default False
**kwargs – Additional keyword arguments passed directly to plotly.express.line See plotly.express.line documentation for all available options

Returns:

Either a plotly figure or the dataframe used for plotting if return_df is True

Return type:

Union[Figure, pl.DataFrame]

ctr_trend(period: str = '1d', facetting=False, *, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False, **kwargs)¶

Create a CTR (Click-Through Rate) trend plot over time.

Parameters:

period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”
facetting (bool, optional) – Whether to create facets by prediction, by default False
query (Optional[QUERY], optional) – Optional query to filter the data, by default None
return_df (bool, optional) – If True, returns the dataframe used for plotting instead of the plot, by default False
**kwargs – Additional keyword arguments passed directly to plotly.express.line See plotly.express.line documentation for all available options

Returns:

Either a plotly figure or the dataframe used for plotting if return_df is True

Return type:

Union[Figure, pl.DataFrame]

responsecount_trend(period: str = '1d', facetting=False, *, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False, **kwargs)¶

Create a response count trend plot showing total responses over time.

Parameters:

period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”
facetting (bool, optional) – Whether to create facets by prediction, by default False
query (Optional[QUERY], optional) – Optional query to filter the data, by default None
return_df (bool, optional) – If True, returns the dataframe used for plotting instead of the plot, by default False
**kwargs – Additional keyword arguments passed directly to plotly.express.line See plotly.express.line documentation for all available options

Returns:

Either a plotly figure or the dataframe used for plotting if return_df is True

Return type:

Union[Figure, pl.DataFrame]

class Prediction(df: polars.LazyFrame, *, query: pdstools.utils.types.QUERY | None = None)¶

Monitor and analyze Pega Prediction Studio Predictions.

To initialize this class, either 1. Initialize directly with the df polars LazyFrame 2. Use one of the class methods

This class will read in the data from different sources, properly structure them for further analysis, and apply correct typing and useful renaming.

There is also a “namespace” that you can call from this class:

.plot contains ready-made plots to analyze the prediction data with

Parameters:

df (pl.LazyFrame) – The Polars LazyFrame representation of the prediction data.
query (QUERY, optional) – An optional query to apply to the input data. For details, see pdstools.utils.cdh_utils._apply_query().

Examples

>>> pred = Prediction.from_ds_export('/my_export_folder/predictions.zip')
>>> pred = Prediction.from_mock_data(days=70)
>>> from pdstools import Prediction
>>> import polars as pl
>>> pred = Prediction(
         df = pl.scan_parquet('predictions.parquet'),
         query = {"Class":["DATA-DECISION-REQUEST-CUSTOMER-CDH"]}
         )

See also

pdstools.utils.cdh_utils._read_pdc: More information on PDC data processing
pdstools.utils.cdh_utils._apply_query: How to query the Prediction class and methods

classmethod from_mock_data(days=70)¶

Create a Prediction instance with mock data for testing and demonstration purposes.

Parameters:: days (int, optional) – Number of days of mock data to generate, by default 70
Returns:: The initialized Prediction class with mock data
Return type:: Prediction

Examples

>>> from pdstools import Prediction
>>> pred = Prediction.from_mock_data(days=30)
>>> pred.plot.performance_trend()

property is_available: bool¶

Check if prediction data is available.

Returns:: True if prediction data is available, False otherwise
Return type:: bool

property is_valid: bool¶

Check if prediction data is valid.

A valid prediction meets the criteria defined in prediction_validity_expr, which requires positive and negative responses in both test and control groups.

Returns:: True if prediction data is valid, False otherwise
Return type:: bool

Summarize prediction per channel

Parameters:

custom_predictions (Optional[List[CDH_Guidelines.NBAD_Prediction]], optional) – Optional list with custom prediction name to channel mappings. Defaults to None.
start_date (datetime.datetime, optional) – Start date of the summary period. If None (default) uses the end date minus the window, or if both absent, the earliest date in the data
end_date (datetime.datetime, optional) – End date of the summary period. If None (default) uses the start date plus the window, or if both absent, the latest date in the data
window (int or datetime.timedelta, optional) – Number of days to use for the summary period or an explicit timedelta. If None (default) uses the whole period. Can’t be given if start and end date are also given.
by_period (str, optional) – Optional additional grouping by time period. Format string as in polars.Expr.dt.truncate (https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.dt.truncate.html), for example “1mo”, “1w”, “1d” for calendar month, week day. Defaults to None.
debug (bool, optional) – If True, enables debug mode for additional logging or outputs. Defaults to False.

Returns:

Summary across all Predictions as a dataframe with the following fields:

Time and Configuration Fields: - DateRange Min - The minimum date in the summary time range - DateRange Max - The maximum date in the summary time range - Duration - The duration in seconds between the minimum and maximum snapshot times - Prediction: The prediction name - Channel: The channel name - Direction: The direction (e.g., Inbound, Outbound) - ChannelDirectionGroup: Combined Channel/Direction identifier - isValid: Boolean indicating if the prediction data is valid - usesNBAD: Boolean indicating if this is a standard NBAD prediction - isMultiChannel: Boolean indicating if this is a multichannel prediction - ControlPercentage: Percentage of responses in control group - TestPercentage: Percentage of responses in test group

Performance Metrics: - Performance: Weighted model performance (AUC) - Positives: Sum of positive responses - Negatives: Sum of negative responses - Responses: Sum of all responses - Positives_Test: Sum of positive responses in test group - Positives_Control: Sum of positive responses in control group - Positives_NBA: Sum of positive responses in NBA group - Negatives_Test: Sum of negative responses in test group - Negatives_Control: Sum of negative responses in control group - Negatives_NBA: Sum of negative responses in NBA group - CTR: Clickthrough rate (Positives over Positives + Negatives) - CTR_Test: Clickthrough rate for test group (model propensitities) - CTR_Control: Clickthrough rate for control group (random propensities) - CTR_NBA: Clickthrough rate for NBA group (available only when Impact Analyzer is used) - Lift: Lift in Engagement when testing prioritization with just Adaptive Models vs just Random Propensity

Technology Usage Indicators: - usesImpactAnalyzer: Boolean indicating if Impact Analyzer is used

Return type:

pl.LazyFrame

Overall prediction summary. Only valid prediction data is included.

Parameters:

custom_predictions (Optional[List[CDH_Guidelines.NBAD_Prediction]], optional) – Optional list with custom prediction name to channel mappings. Defaults to None.
start_date (datetime.datetime, optional) – Start date of the summary period. If None (default) uses the end date minus the window, or if both absent, the earliest date in the data
end_date (datetime.datetime, optional) – End date of the summary period. If None (default) uses the start date plus the window, or if both absent, the latest date in the data
window (int or datetime.timedelta, optional) – Number of days to use for the summary period or an explicit timedelta. If None (default) uses the whole period. Can’t be given if start and end date are also given.
by_period (str, optional) – Optional additional grouping by time period. Format string as in polars.Expr.dt.truncate (https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.dt.truncate.html), for example “1mo”, “1w”, “1d” for calendar month, week day. Defaults to None.
debug (bool, optional) – If True, enables debug mode for additional logging or outputs. Defaults to False.

Returns:

Summary across all Predictions as a dataframe with the following fields:

Time and Configuration Fields: - DateRange Min - The minimum date in the summary time range - DateRange Max - The maximum date in the summary time range - Duration - The duration in seconds between the minimum and maximum snapshot times - ControlPercentage: Weighted average percentage of control group responses - TestPercentage: Weighted average percentage of test group responses - usesNBAD: Boolean indicating if any of the predictions is a standard NBAD prediction

Performance Metrics: - Performance: Weighted average performance across all valid channels - Positives Inbound: Sum of positive responses across all valid inbound channels - Positives Outbound: Sum of positive responses across all valid outbound channels - Responses Inbound: Sum of all responses across all valid inbound channels - Responses Outbound: Sum of all responses across all valid outbound channels - Overall Lift: Weighted average lift across all valid channels - Minimum Negative Lift: The lowest negative lift value found

Channel Statistics: - Number of Valid Channels: Count of unique valid channel/direction combinations - Channel with Minimum Negative Lift: Channel with the lowest negative lift value

Technology Usage Indicators: - usesImpactAnalyzer: Boolean indicating if any channel uses Impact Analyzer

Return type:

pl.LazyFrame