pdstools.ih.Plots

Plotting utilities for Interaction History visualization.

Attributes

logger

Classes

Plots

Visualization methods for Interaction History data.

Module Contents

logger
class Plots(ih: pdstools.ih.IH.IH)

Bases: pdstools.utils.namespaces.LazyNamespace

Visualization methods for Interaction History data.

This class provides plotting capabilities for analyzing customer interaction data. It is accessed through the plot attribute of an IH instance.

All plot methods support: - Custom titles via title parameter - Data filtering via query parameter - Returning underlying data via return_df=True

Parameters:

ih (pdstools.ih.IH.IH)

ih

Reference to the parent IH instance.

Type:

IH

See also

pdstools.ih.IH

Main analysis class.

pdstools.ih.Aggregates

Aggregation methods.

Examples

>>> ih = IH.from_ds_export("interaction_history.zip")
>>> ih.plot.success_rate(metric="Engagement")
>>> ih.plot.response_count_tree_map()
ih
overall_gauges(condition: str | polars.Expr, *, metric: str = 'Engagement', by: str = 'Channel', reference_values: Dict[str, float] | None = None, title: str | None = None, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create gauge charts showing success rates by condition and dimension.

Generates a grid of gauge charts displaying success rates for combinations of the specified condition and grouping dimension, with optional reference values for comparison.

Parameters:

  • condition (Union[str, pl.Expr]) – Column to condition on (e.g., “Experiment”, “Issue”).

  • metric (str, default "Engagement") – Metric to display: “Engagement”, “Conversion”, or “OpenRate”.

  • by (str, default "Channel") – Dimension for grouping (column name).

  • reference_values (Dict[str, float], optional) – Reference values per dimension for comparison thresholds.

  • title (str, optional) – Custom title. If None, auto-generated from metric.

  • query (QUERY, optional) – Polars expression to filter the data.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly figure, or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

Examples

>>> ih.plot.overall_gauges("Issue", metric="Engagement", by="Channel")
response_count_tree_map(*, by: List[str] | None = None, title: str | None = None, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create a treemap of response count distribution.

Displays hierarchical response counts across dimensions, allowing exploration of how responses are distributed across categories.

Parameters:

  • by (List[str], optional) – Hierarchy dimensions. Defaults to Direction, Channel, Issue, Group, Name.

  • title (str, optional) – Custom title.

  • query (QUERY, optional) – Polars expression to filter the data.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly treemap, or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

See also

success_rate_tree_map

Treemap colored by success rates.

Examples

>>> ih.plot.response_count_tree_map()
>>> ih.plot.response_count_tree_map(by=["Channel", "Issue", "Name"])
success_rate_tree_map(*, metric: str = 'Engagement', by: List[str] | None = None, title: str | None = None, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create a treemap colored by success rates.

Displays hierarchical success rates across dimensions, with color indicating performance levels for easy identification of high and low performing areas.

Parameters:

  • metric (str, default "Engagement") – Metric to display: “Engagement”, “Conversion”, or “OpenRate”.

  • by (List[str], optional) – Hierarchy dimensions. Defaults to Direction, Channel, Issue, Group, Name.

  • title (str, optional) – Custom title. If None, auto-generated from metric.

  • query (QUERY, optional) – Polars expression to filter the data.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly treemap, or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

See also

response_count_tree_map

Treemap by response counts.

Examples

>>> ih.plot.success_rate_tree_map(metric="Conversion")
action_distribution(*, by: str = 'Name', title: str = 'Action Distribution', query: pdstools.utils.types.QUERY | None = None, color: str | None = None, facet: str | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create a bar chart of action distribution.

Displays action counts across categories, optionally colored and faceted by additional dimensions.

Parameters:

  • by (str, default "Name") – Dimension for y-axis categories.

  • title (str, default "Action Distribution") – Chart title.

  • query (QUERY, optional) – Polars expression to filter the data.

  • color (str, optional) – Dimension for bar coloring.

  • facet (str, optional) – Dimension for faceting.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly bar chart, or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

Examples

>>> ih.plot.action_distribution(by="Name", color="Channel")
success_rate(*, metric: str = 'Engagement', every: str | datetime.timedelta = '1d', title: str | None = None, query: pdstools.utils.types.QUERY | None = None, facet: str | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create a line chart of success rates over time.

Displays success rate trends for the specified metric, optionally faceted by dimension for comparative analysis.

Parameters:

  • metric (str, default "Engagement") – Metric to display: “Engagement”, “Conversion”, or “OpenRate”.

  • every (str or timedelta, default "1d") – Time aggregation period (e.g., “1d”, “1w”, “1mo”).

  • title (str, optional) – Custom title. If None, auto-generated from metric.

  • query (QUERY, optional) – Polars expression to filter the data.

  • facet (str, optional) – Dimension for faceting and coloring.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly line chart, or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

See also

response_count

Response counts over time.

model_performance_trend

Model AUC over time.

Examples

>>> ih.plot.success_rate(metric="Conversion", every="1w")
response_count(*, every: str | datetime.timedelta = '1d', title: str = 'Responses', query: pdstools.utils.types.QUERY | None = None, facet: str | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create a bar chart of response counts over time.

Displays response counts colored by outcome type, optionally faceted by dimension.

Parameters:

  • every (str or timedelta, default "1d") – Time aggregation period (e.g., “1d”, “1w”, “1mo”).

  • title (str, default "Responses") – Chart title.

  • query (QUERY, optional) – Polars expression to filter the data.

  • facet (str, optional) – Dimension for faceting.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly bar chart, or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

See also

success_rate

Success rates over time.

Examples

>>> ih.plot.response_count(every="1w", facet="Channel")
model_performance_trend(*, metric: str = 'Engagement', every: str | datetime.timedelta = '1d', by: str | None = None, title: str = 'Model Performance over Time', query: pdstools.utils.types.QUERY | None = None, facet: str | None = None, return_df: bool = False) → plotly.graph_objs.Figure | polars.LazyFrame

Create a line chart of model AUC over time.

Displays model performance (Area Under the ROC Curve) calculated from propensity scores and actual outcomes. Higher AUC indicates better predictive accuracy.

Parameters:

  • metric (str, default "Engagement") – Metric for AUC calculation: “Engagement”, “Conversion”, or “OpenRate”.

  • every (str or timedelta, default "1d") – Time aggregation period (e.g., “1d”, “1w”, “1mo”).

  • by (str, optional) – Dimension for line coloring.

  • title (str, default "Model Performance over Time") – Chart title.

  • query (QUERY, optional) – Polars expression to filter the data.

  • facet (str, optional) – Dimension for faceting.

  • return_df (bool, default False) – If True, return data as LazyFrame instead of figure.

Returns:

Plotly line chart (y-axis in AUC percentage), or LazyFrame if return_df=True.

Return type:

Figure or pl.LazyFrame

See also

success_rate

Success rate trends.

Examples

>>> ih.plot.model_performance_trend(by="Channel", every="1w")