pdstools.prediction.Plots

Attributes

logger

Classes

PredictionPlots

Plots for visualizing Prediction Studio data.

Module Contents

logger
class PredictionPlots(prediction: pdstools.prediction.Prediction.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.

Parameters:

prediction (pdstools.prediction.Prediction.Prediction)

dependencies = ['plotly']
dependency_group = 'adm'
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 = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[False] = ..., **kwargs) → plotly.graph_objects.Figure
performance_trend(period: str = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[True], **kwargs) → polars.LazyFrame

Create a performance trend plot showing AUC over time.

Displays a line chart showing how prediction performance (AUC) changes over time, with configurable time period aggregation and filtering capabilities.

Parameters:

  • period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”. Uses Polars truncate syntax for time period grouping.

  • query (Optional[QUERY], optional) – Query to filter the prediction data. See pdstools.utils.cdh_utils._apply_query for details.

  • return_df (bool, optional) – If True, returns the underlying data 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:

A Plotly figure object or the underlying data if return_df is True.

Return type:

Union[plotly.graph_objects.Figure, polars.LazyFrame]

Examples

>>> # Basic performance trend plot
>>> pred.plot.performance_trend()

>>> # Weekly aggregated performance trend
>>> pred.plot.performance_trend(period="1w")

>>> # Performance trend with faceting by prediction
>>> pred.plot.performance_trend(facet_row="Prediction")

>>> # Get underlying data for custom analysis
>>> data = pred.plot.performance_trend(return_df=True)
lift_trend(period: str = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[False] = ..., **kwargs) → plotly.graph_objects.Figure
lift_trend(period: str = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[True], **kwargs) → polars.LazyFrame

Create a lift trend plot showing engagement lift over time.

Displays a line chart showing how prediction engagement lift changes over time, comparing test group performance against control group baseline.

Parameters:

  • period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”. Uses Polars truncate syntax for time period grouping.

  • query (Optional[QUERY], optional) – Query to filter the prediction data. See pdstools.utils.cdh_utils._apply_query for details.

  • return_df (bool, optional) – If True, returns the underlying data 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:

A Plotly figure object or the underlying data if return_df is True.

Return type:

Union[plotly.graph_objects.Figure, polars.LazyFrame]

Examples

>>> # Basic lift trend plot
>>> pred.plot.lift_trend()

>>> # Monthly aggregated lift trend
>>> pred.plot.lift_trend(period="1mo")

>>> # Lift trend with custom query
>>> pred.plot.lift_trend(query=pl.col("Channel") == "Email")

>>> # Get underlying data
>>> data = pred.plot.lift_trend(return_df=True)
ctr_trend(period: str = ..., facetting: bool = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[False] = ..., **kwargs) → plotly.graph_objects.Figure
ctr_trend(period: str = ..., facetting: bool = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[True], **kwargs) → polars.LazyFrame

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

Displays a line chart showing how prediction click-through rates change over time, with optional faceting capabilities for comparing multiple predictions.

Parameters:

  • period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”. Uses Polars truncate syntax for time period grouping.

  • facetting (bool, optional) – Whether to create facets by prediction for side-by-side comparison, by default False.

  • query (Optional[QUERY], optional) – Query to filter the prediction data. See pdstools.utils.cdh_utils._apply_query for details.

  • return_df (bool, optional) – If True, returns the underlying data 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:

A Plotly figure object or the underlying data if return_df is True.

Return type:

Union[plotly.graph_objects.Figure, polars.LazyFrame]

Examples

>>> # Basic CTR trend plot
>>> pred.plot.ctr_trend()

>>> # Weekly CTR trend with faceting
>>> pred.plot.ctr_trend(period="1w", facetting=True)

>>> # CTR trend with custom query
>>> pred.plot.ctr_trend(query=pl.col("Prediction").str.contains("Email"))

>>> # Get underlying data
>>> data = pred.plot.ctr_trend(return_df=True)
responsecount_trend(period: str = ..., facetting: bool = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[False] = ..., **kwargs) → plotly.graph_objects.Figure
responsecount_trend(period: str = ..., facetting: bool = ..., *, query: pdstools.utils.types.QUERY | None = ..., return_df: Literal[True], **kwargs) → polars.LazyFrame

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

Displays a line chart showing how total response volumes change over time, useful for monitoring prediction usage and data volume trends.

Parameters:

  • period (str, optional) – Time period for aggregation (e.g., “1d”, “1w”, “1mo”), by default “1d”. Uses Polars truncate syntax for time period grouping.

  • facetting (bool, optional) – Whether to create facets by prediction for side-by-side comparison, by default False.

  • query (Optional[QUERY], optional) – Query to filter the prediction data. See pdstools.utils.cdh_utils._apply_query for details.

  • return_df (bool, optional) – If True, returns the underlying data 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:

A Plotly figure object or the underlying data if return_df is True.

Return type:

Union[plotly.graph_objects.Figure, polars.LazyFrame]

Examples

>>> # Basic response count trend plot
>>> pred.plot.responsecount_trend()

>>> # Monthly response count trend with faceting
>>> pred.plot.responsecount_trend(period="1mo", facetting=True)

>>> # Response count trend for specific predictions
>>> pred.plot.responsecount_trend(query=pl.col("Channel") == "Web")

>>> # Get underlying data for analysis
>>> data = pred.plot.responsecount_trend(return_df=True)