dpg.visualizer#

Functions#

plot_dpg(plot_name, dot, df, df_edges[, save_dir, ...])

Plot a Decision Predicate Graph (DPG) with optional node/edge styling.

plot_dpg_communities(plot_name, dot, df, dpg_metrics)

Plot a DPG colored by community assignment.

plot_dpg_local_paths_aggregate(plot_name, dot, df, ...)

Plot a fitted DPG with one sample's local paths highlighted on top.

change_node_color(→ None)

Update a node's fill color and set an appropriate contrasting font color.

normalize_data(→ Dict[Any, str])

Map a numeric DataFrame column to hex color strings via a colormap.

plot_dpg_reg(→ None)

Plot a regression DPG with optional node coloring by attribute or community.

plot_dpg_constraints_overview(→ Any)

Create a horizontal bar chart showing DPG constraints for all features.

parse_predicate_parts(→ Optional[Tuple[str, str, float]])

Parse predicate labels like 'feature <= 1.23' or 'feature > 0.7'.

parse_feature_from_predicate(→ str)

Extract the feature name from a predicate label string.

lrc_predicate_scores(→ Any)

Return top-k predicate rows ranked by Local reaching centrality.

plot_lrc_vs_rf_importance(→ Any)

Compare top LRC predicates and top RF feature importances side-by-side.

plot_lec_vs_rf_importance(→ Any)

Backward-compatible alias for a common typo.

plot_top_lrc_predicate_splits(→ Optional[Any])

Scatter the top-2 LRC features and overlay top-LRC predicate split lines.

sample_bc_weights(→ Any)

Compute a per-sample bottleneck exposure score from top-BC predicates.

plot_sample_using_bc_weights(→ Any)

Plot samples in PCA space with marker size driven by BC-derived weights.

class_feature_predicate_counts(→ Any)

Compute class-vs-feature predicate frequency table from DPG communities.

plot_class_feature_complexity(→ Tuple[Any, Any])

Plot class-feature predicate complexity with PCA-consistent class colors.

classwise_feature_bounds_from_communities(→ Any)

Build per-class, per-community finite/unbounded feature ranges from predicates.

class_feature_predicate_positions(→ Any)

Collect raw predicate thresholds by class/feature/operator for density overlays.

class_lookup_from_target_names(→ Dict[str, int])

Build a class-name to class-index mapping from a target names list.

dataset_feature_bounds_by_class(→ Any)

Compute empirical per-class min/max ranges for every feature in X_df.

plot_dpg_class_bounds_vs_dataset_feature_ranges(...)

Plot DPG class bounds against empirical dataset ranges per feature.

change_edge_color(graph, source_id, target_id, ...)

Changes the color and dimension (penwidth) of a specified edge in the Graphviz Digraph.

Module Contents#

dpg.visualizer.plot_dpg(plot_name, dot, df, df_edges, save_dir='results/', attribute=None, clusters=None, threshold_clusters=None, class_flag=False, layout_template='default', graph_style=None, node_style=None, edge_style=None, fig_size=(16, 8), dpi=300, pdf_dpi=600, show=True, export_pdf=False, theme: str = 'dpg', palette: str = 'default', label_mode: str = 'full', readability: str = 'normal', title: str | None = None)[source]#

Plot a Decision Predicate Graph (DPG) with optional node/edge styling.

Parameters:

  • plot_name – Output base name for saved files (no extension).

  • dot – Graphviz Digraph instance representing the DPG structure.

  • df – DataFrame with node metrics; must include 'Node' and 'Label' columns.

  • df_edges – DataFrame with edge metrics; must include 'Source_id', 'Target_id', and 'Weight'.

  • save_dir – Directory where output images are saved. Default is "results/".

  • attribute – Optional node metric column name to color nodes by (e.g. 'Degree').

  • clusters – Optional mapping {cluster_label: [node_id, ...]} to color nodes by cluster membership.

  • threshold_clusters – Optional value used only to annotate the output filename.

  • class_flag – If True, class nodes are highlighted in yellow before other coloring.

  • layout_template – Optional layout preset. One of {'default', 'compact', 'vertical', 'wide'}.

  • graph_style – Optional dict of Graphviz graph attributes to override template values.

  • node_style – Optional dict of Graphviz node attributes to override template values.

  • edge_style – Optional dict of Graphviz edge attributes to override template values.

  • fig_size – Matplotlib figure size as (width, height).

  • dpi – PNG export/display resolution.

  • pdf_dpi – PDF export resolution when export_pdf=True.

  • show – Whether to display the image via Matplotlib. Default is True.

  • export_pdf – If True, also writes a PDF next to the PNG.

  • label_mode – Label formatting strategy. One of {'full', 'wrapped', 'short'}.

  • readability – Graph spacing/readability preset. One of {'compact', 'normal', 'presentation'}.

Returns:

None

dpg.visualizer.plot_dpg_communities(plot_name, dot, df, dpg_metrics, save_dir='results/', class_flag=False, df_edges=None, layout_template='default', graph_style=None, node_style=None, edge_style=None, fig_size=(16, 8), dpi=300, pdf_dpi=600, show=True, export_pdf=False, theme: str = 'dpg', palette: str = 'default', label_mode: str = 'wrapped', readability: str = 'presentation', title: str | None = None)[source]#

Plot a DPG colored by community assignment.

Parameters:

  • plot_name – Output base name for saved files (no extension).

  • dot – Graphviz Digraph instance representing the DPG structure.

  • df – DataFrame with node metrics; must include 'Node' and 'Label' columns.

  • dpg_metrics – Dict containing either 'Communities' (list of sets/lists of node labels) or 'Clusters' (mapping cluster_label -> list of node labels).

  • save_dir – Directory where output images are saved. Default is "results/".

  • class_flag – If True, class nodes are highlighted in yellow before other coloring.

  • df_edges – Optional DataFrame with edge metrics to color edges by weight.

  • layout_template – Optional layout preset. One of {'default', 'compact', 'vertical', 'wide'}.

  • graph_style – Optional dict of Graphviz graph attributes to override template values.

  • node_style – Optional dict of Graphviz node attributes to override template values.

  • edge_style – Optional dict of Graphviz edge attributes to override template values.

  • fig_size – Matplotlib figure size as (width, height).

  • dpi – PNG export/display resolution.

  • pdf_dpi – PDF export resolution when export_pdf=True.

  • show – Whether to display the image via Matplotlib. Default is True.

  • export_pdf – If True, also writes a PDF next to the PNG.

  • label_mode – Label formatting strategy. One of {'full', 'wrapped', 'short'}.

  • readability – Graph spacing/readability preset. One of {'compact', 'normal', 'presentation'}.

Returns:

None

dpg.visualizer.plot_dpg_local_paths_aggregate(plot_name, dot, df, df_edges, paths_node_ids, path_confidences=None, sample_id=None, true_class_label=None, obtained_class_label=None, sample_metrics=None, save_dir='results/', class_flag=True, layout_template='default', graph_style=None, node_style=None, edge_style=None, fig_size=(16, 8), dpi=300, pdf_dpi=600, show=True, export_pdf=False, theme: str = 'dpg', palette: str = 'default', label_mode: str = 'wrapped', readability: str = 'presentation', title: str | None = None)[source]#

Plot a fitted DPG with one sample’s local paths highlighted on top.

Args mirror the existing DPG plot API, with local path overlays passed as ordered node-id paths and optional per-path confidence weights.

Returns:

matplotlib.figure.Figure

dpg.visualizer.change_node_color(dot, node_id: str, fillcolor: str) → None[source]#

Update a node’s fill color and set an appropriate contrasting font color.

Parameters:

  • dot – Graphviz Digraph object to modify in-place.

  • node_id – Node identifier string as used in the Digraph.

  • fillcolor – Hex color string (e.g. "#a4c2f4").

dpg.visualizer.normalize_data(df: Any, attribute: str, colormap) → Dict[Any, str][source]#

Map a numeric DataFrame column to hex color strings via a colormap.

Parameters:

  • df – DataFrame containing at least a 'Node' column and the attribute column.

  • attribute – Column name whose values drive the colormap.

  • colormap – Matplotlib colormap instance.

Returns:

Dict mapping node identifier to hex color string.

dpg.visualizer.plot_dpg_reg(plot_name: str, dot, df: Any, df_dpg: Dict[str, Any], save_dir: str = 'examples/', attribute: str | None = None, communities: bool = False, leaf_flag: bool = False, theme: str = 'dpg', palette: str = 'default') → None[source]#

Plot a regression DPG with optional node coloring by attribute or community.

Parameters:

  • plot_name – Output base name for saved files (no extension).

  • dot – Graphviz Digraph instance representing the DPG structure.

  • df – DataFrame with node metrics; must include 'Node' and 'Label' columns.

  • df_dpg – Dict of DPG metrics; used for 'Communities' when communities=True.

  • save_dir – Directory where output images are saved. Default is "examples/".

  • attribute – Optional node metric column name to color nodes by.

  • communities – If True, color nodes by community index instead of a single attribute.

  • leaf_flag – If True and attribute is set, exclude prediction (leaf) nodes from attribute coloring.

dpg.visualizer.plot_dpg_constraints_overview(normalized_constraints: Dict, feature_names: List[str], class_colors_list: List[str], output_path: str = None, title: str = 'DPG Constraints Overview', original_sample: Dict = None, original_class: int = None, target_class: int = None, theme: str = 'dpg', palette: str = 'default') → Any[source]#

Create a horizontal bar chart showing DPG constraints for all features.

Similar to the “Feature Changes” chart style, this shows: - Original sample values as markers/bars - Constraint boundaries (min/max) for original and target classes as colored regions

Parameters:

  • normalized_constraints – Dict with structure {class_name: {feature: {min, max}}}

  • feature_names – List of feature names to display

  • class_colors_list – List of colors for each class

  • output_path – Optional path to save the figure

  • title – Title for the figure

  • original_sample – Optional dict of original sample feature values

  • original_class – Optional original class index (for highlighting)

  • target_class – Optional target class index (for highlighting)

Returns:

matplotlib Figure object

dpg.visualizer.parse_predicate_parts(label: str) → Tuple[str, str, float] | None[source]#

Parse predicate labels like ‘feature <= 1.23’ or ‘feature > 0.7’.

dpg.visualizer.parse_feature_from_predicate(label: str) → str[source]#

Extract the feature name from a predicate label string.

Parameters:

label – Predicate string such as "petal_length <= 2.45".

Returns:

Feature name, or the original label string if parsing fails.

dpg.visualizer.lrc_predicate_scores(explanation, top_k: int = 10) → Any[source]#

Return top-k predicate rows ranked by Local reaching centrality.

dpg.visualizer.plot_lrc_vs_rf_importance(explanation, model, X_df: Any, top_k: int = 10, dataset_name: str = 'Dataset', save_path: str | None = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') → Any[source]#

Compare top LRC predicates and top RF feature importances side-by-side.

Returns:

Matplotlib figure.

dpg.visualizer.plot_lec_vs_rf_importance(*args, **kwargs) → Any[source]#

Backward-compatible alias for a common typo.

Use plot_lrc_vs_rf_importance instead.

dpg.visualizer.plot_top_lrc_predicate_splits(explanation, X_df: Any, y, top_predicates: int = 5, top_features: int = 2, dataset_name: str = 'Dataset', class_names: Any | None = None, save_path: str | None = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') → Any | None[source]#

Scatter the top-2 LRC features and overlay top-LRC predicate split lines.

Returns:

Matplotlib figure, or None when top features cannot be resolved.

dpg.visualizer.sample_bc_weights(explanation, X_df: Any, top_k: int = 10) → Any[source]#

Compute a per-sample bottleneck exposure score from top-BC predicates.

This is not a graph-theoretic BC computed on samples themselves. Instead, each sample receives the sum of the betweenness-centrality scores of the top-k predicate nodes it satisfies:

weight(sample_i) = sum_p 1[sample_i satisfies predicate_p] * BC(predicate_p)

Parameters:

  • explanation – Global DPG explanation containing node_metrics.

  • X_df – Feature matrix as a pandas DataFrame.

  • top_k – Number of highest-BC predicate nodes to include.

Returns:

pandas Series indexed like X_df with one BC-derived weight per sample.

dpg.visualizer.plot_sample_using_bc_weights(explanation, X_df: Any, y, top_k: int = 10, dataset_name: str = 'Dataset', class_names: Any | None = None, save_path: str | None = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') → Any[source]#

Plot samples in PCA space with marker size driven by BC-derived weights.

Marker size reflects the sum of BC scores from the top-k predicate nodes satisfied by each sample. Large points therefore indicate samples that activate more bottleneck predicates in the DPG.

dpg.visualizer.class_feature_predicate_counts(explanation) → Any[source]#

Compute class-vs-feature predicate frequency table from DPG communities.

Returns:

DataFrame indexed by class, columns as features, values as counts.

dpg.visualizer.plot_class_feature_complexity(heat_df: Any, dataset_name: str = 'Dataset', class_names: Any | None = None, top_n_features: int = 10, save_prefix: str | None = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') → Tuple[Any, Any][source]#

Plot class-feature predicate complexity with PCA-consistent class colors.

Produces: - *_heatmap.png: heatmap with class color strip and class-colored labels - *_bars.png: grouped bar chart with one color per class

dpg.visualizer.classwise_feature_bounds_from_communities(explanation) → Any[source]#

Build per-class, per-community finite/unbounded feature ranges from predicates.

dpg.visualizer.class_feature_predicate_positions(explanation) → Any[source]#

Collect raw predicate thresholds by class/feature/operator for density overlays.

dpg.visualizer.class_lookup_from_target_names(target_names: List[str] | None) → Dict[str, int][source]#

Build a class-name to class-index mapping from a target names list.

Parameters:

target_names – Ordered list of class name strings (e.g. from sklearn.LabelEncoder.classes_), or None.

Returns:

Dict mapping class name string to integer index, or an empty dict when target_names is None.

dpg.visualizer.dataset_feature_bounds_by_class(X_df: Any, y, class_names: List[str], class_lookup: Dict[str, int] | None = None) → Any[source]#

Compute empirical per-class min/max ranges for every feature in X_df.

Parameters:

  • X_df – Feature matrix with named columns.

  • y – Target labels aligned with X_df rows.

  • class_names – List of class name strings to compute bounds for.

  • class_lookup – Optional mapping from class name to numeric label used in y.

Returns:

DataFrame with columns ['class_name', 'feature', 'ds_lower_bound', 'ds_upper_bound'].

dpg.visualizer.plot_dpg_class_bounds_vs_dataset_feature_ranges(explanation, X_df: Any, y, dataset_name: str = 'Dataset', top_features: int = 4, feature_cols_per_row: int = 4, class_lookup: Dict[str, int] | None = None, predicate_positions: Any | None = None, class_bounds: Any | None = None, class_filter: List[str] | None = None, density_tol_ratio: float = 0.03, predicate_alpha: float = 0.55, dataset_range_lw: float = 10, save_path: str | None = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') → Any | None[source]#

Plot DPG class bounds against empirical dataset ranges per feature.

Parameters:

  • explanation – DPGExplanation instance.

  • X_df – Feature dataframe.

  • y – Class labels aligned with X_df.

  • feature_cols_per_row – Number of feature panels per row block.

  • class_lookup – Optional class-name to class-id mapping.

  • predicate_positions – Optional precomputed output from class_feature_predicate_positions.

  • class_bounds – Optional precomputed output from classwise_feature_bounds_from_communities.

  • class_filter – Optional class or list of classes to render.

Returns:

Matplotlib figure, or None when no plottable classes exist.

dpg.visualizer.change_edge_color(graph, source_id, target_id, new_color, new_width)[source]#

Changes the color and dimension (penwidth) of a specified edge in the Graphviz Digraph.

Parameters:

  • graph – A Graphviz Digraph object.

  • source_id – The source node of the edge.

  • target_id – The target node of the edge.

  • new_color – The new color to be applied to the edge.

  • new_width – The new penwidth (edge thickness) to be applied.

Returns:

None