pdstools.adm.Plots._overview

Model-overview plots: bubble_chart, tree_map, action_overlap, partitioned_plot.

Classes

_OverviewPlotsMixin

Common attribute surface used by every plot mixin.

Module Contents

class _OverviewPlotsMixin

Bases: pdstools.adm.Plots._base._PlotsBase

Common attribute surface used by every plot mixin.

bubble_chart(*, last: bool = True, rounding: int = 5, query: pdstools.utils.types.QUERY | None = None, facet: str | polars.Expr | None = None, color: str | None = 'Performance', show_metric_limits: bool = False, return_df: bool = False)

The Bubble Chart, as seen in Prediction Studio

Parameters:

  • last (bool, optional) – Whether to only include the latest snapshot, by default True

  • rounding (int, optional) – To how many digits to round the performance number

  • query (Optional[QUERY], optional) – The query to apply to the data, by default None

  • facet (Optional[Union[str, pl.Expr]], optional) – Column name or Polars expression to facet the plot into subplots, by default None

  • show_metric_limits (bool, optional) – Whether to show dashed vertical lines at the ModelPerformance metric limit thresholds (from MetricLimits.csv), by default False

  • return_df (bool, optional) – Whether to return a dataframe instead of a plot, by default False

  • color (str | None)

Returns:

Plotly scatter figure or LazyFrame if return_df=True

Return type:

Figure | pl.LazyFrame

Examples

>>> from pdstools import ADMDatamart
>>> dm = ADMDatamart.from_ds_export(base_path="/my_export_folder")

>>> # Basic bubble chart using the latest snapshot
>>> fig = dm.plot.bubble_chart()

>>> # Facet by Channel to see performance per channel
>>> fig = dm.plot.bubble_chart(facet="Channel")

>>> # Include all snapshots and show metric-limit guidelines
>>> fig = dm.plot.bubble_chart(last=False, show_metric_limits=True)

>>> # Return the underlying data instead of the figure
>>> df = dm.plot.bubble_chart(return_df=True)
tree_map(metric: Literal['ResponseCount', 'Positives', 'Performance', 'SuccessRate', 'percentage_without_responses'] = 'Performance', *, by: str = 'Name', query: pdstools.utils.types.QUERY | None = None, return_df: bool = False)

Generate a tree map visualization showing hierarchical model metrics.

Parameters:

  • metric (Literal["ResponseCount", "Positives", "Performance", "SuccessRate", "percentage_without_responses"], optional) – The metric to visualize in the tree map, by default “Performance”

  • by (str, optional) – Column to group by for the tree map hierarchy, by default “Name”

  • query (Optional[QUERY], optional) – Optional query to filter the data, by default None

  • return_df (bool, optional) – Whether to return a dataframe instead of a plot, by default False

Returns:

Plotly treemap figure or DataFrame if return_df=True

Return type:

Union[Figure, pl.LazyFrame]

Examples

>>> # Default: Performance tree map grouped by proposition name
>>> fig = dm.plot.tree_map()

>>> # ResponseCount tree map grouped by Channel
>>> fig = dm.plot.tree_map(metric="ResponseCount", by="Channel")

>>> # Return underlying summary data
>>> df = dm.plot.tree_map(return_df=True)
action_overlap(group_col: str | list[str] | polars.Expr = 'Channel', overlap_col='Name', *, show_fraction=True, query: pdstools.utils.types.QUERY | None = None, return_df: bool = False)

Generate an overlap matrix heatmap showing shared actions across different groups.

Parameters:

  • group_col (Union[str, list[str], pl.Expr], optional) – Column(s) to group by for overlap analysis, by default “Channel”

  • overlap_col (str, optional) – Column containing values to analyze for overlap, by default “Name”

  • show_fraction (bool, optional) – Whether to show overlap as fraction or absolute count, by default True

  • query (Optional[QUERY], optional) – Optional query to filter the data, by default None

  • return_df (bool, optional) – Whether to return a dataframe instead of a plot, by default False

Returns:

Plotly heatmap showing action overlap or DataFrame if return_df=True

Return type:

Union[Figure, pl.LazyFrame]

Examples

>>> # Default: action overlap across Channels
>>> fig = dm.plot.action_overlap()

>>> # Overlap shown as absolute counts rather than fractions
>>> fig = dm.plot.action_overlap(show_fraction=False)

>>> # Overlap of configurations across Channel/Direction combinations
>>> fig = dm.plot.action_overlap(
...     group_col=["Channel", "Direction"],
...     overlap_col="Configuration",
... )

>>> # Return the overlap matrix as a DataFrame
>>> df = dm.plot.action_overlap(return_df=True)
partitioned_plot(func: collections.abc.Callable, facets: list[dict[str, str | None]], show_plots: bool = True, *args, **kwargs)

Execute a plotting function across multiple faceted subsets of data.

This method applies a given plotting function to multiple filtered subsets of data, where each subset is defined by the facet conditions. It’s useful for generating multiple plots with different filter conditions applied.

Parameters:

  • func (Callable) – The plotting function to execute for each facet

  • facets (list[dict[str, Optional[str]]]) – list of dictionaries defining filter conditions for each facet

  • show_plots (bool, optional) – Whether to display the plots as they are generated, by default True

  • *args (tuple) – Additional positional arguments to pass to the plotting function

  • **kwargs (dict) – Additional keyword arguments to pass to the plotting function

Returns:

list of Plotly figures, one for each facet condition

Return type:

list[Figure]

Examples

>>> # Bubble chart separately for Web and Email channels
>>> figs = dm.plot.partitioned_plot(
...     dm.plot.bubble_chart,
...     facets=[{"Channel": "Web"}, {"Channel": "Email"}],
... )

>>> # Same but suppress auto-display
>>> figs = dm.plot.partitioned_plot(
...     dm.plot.bubble_chart,
...     facets=[{"Channel": "Web"}, {"Channel": "Email"}],
...     show_plots=False,
... )