dpg.visualizer ============== .. py:module:: dpg.visualizer Functions --------- .. autoapisummary:: dpg.visualizer.plot_dpg dpg.visualizer.plot_dpg_communities dpg.visualizer.plot_dpg_local_paths_aggregate dpg.visualizer.change_node_color dpg.visualizer.normalize_data dpg.visualizer.plot_dpg_reg dpg.visualizer.plot_dpg_constraints_overview dpg.visualizer.parse_predicate_parts dpg.visualizer.parse_feature_from_predicate dpg.visualizer.lrc_predicate_scores dpg.visualizer.plot_lrc_vs_rf_importance dpg.visualizer.plot_lec_vs_rf_importance dpg.visualizer.plot_top_lrc_predicate_splits dpg.visualizer.sample_bc_weights dpg.visualizer.plot_sample_using_bc_weights dpg.visualizer.class_feature_predicate_counts dpg.visualizer.plot_class_feature_complexity dpg.visualizer.classwise_feature_bounds_from_communities dpg.visualizer.class_feature_predicate_positions dpg.visualizer.class_lookup_from_target_names dpg.visualizer.dataset_feature_bounds_by_class dpg.visualizer.plot_dpg_class_bounds_vs_dataset_feature_ranges dpg.visualizer.change_edge_color Module Contents --------------- .. py:function:: 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: Optional[str] = None) Plot a Decision Predicate Graph (DPG) with optional node/edge styling. :param plot_name: Output base name for saved files (no extension). :param dot: Graphviz Digraph instance representing the DPG structure. :param df: DataFrame with node metrics; must include ``'Node'`` and ``'Label'`` columns. :param df_edges: DataFrame with edge metrics; must include ``'Source_id'``, ``'Target_id'``, and ``'Weight'``. :param save_dir: Directory where output images are saved. Default is ``"results/"``. :param attribute: Optional node metric column name to color nodes by (e.g. ``'Degree'``). :param clusters: Optional mapping ``{cluster_label: [node_id, ...]}`` to color nodes by cluster membership. :param threshold_clusters: Optional value used only to annotate the output filename. :param class_flag: If ``True``, class nodes are highlighted in yellow before other coloring. :param layout_template: Optional layout preset. One of ``{'default', 'compact', 'vertical', 'wide'}``. :param graph_style: Optional dict of Graphviz graph attributes to override template values. :param node_style: Optional dict of Graphviz node attributes to override template values. :param edge_style: Optional dict of Graphviz edge attributes to override template values. :param fig_size: Matplotlib figure size as ``(width, height)``. :param dpi: PNG export/display resolution. :param pdf_dpi: PDF export resolution when ``export_pdf=True``. :param show: Whether to display the image via Matplotlib. Default is ``True``. :param export_pdf: If ``True``, also writes a PDF next to the PNG. :param label_mode: Label formatting strategy. One of ``{'full', 'wrapped', 'short'}``. :param readability: Graph spacing/readability preset. One of ``{'compact', 'normal', 'presentation'}``. :returns: None .. py:function:: 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: Optional[str] = None) Plot a DPG colored by community assignment. :param plot_name: Output base name for saved files (no extension). :param dot: Graphviz Digraph instance representing the DPG structure. :param df: DataFrame with node metrics; must include ``'Node'`` and ``'Label'`` columns. :param dpg_metrics: Dict containing either ``'Communities'`` (list of sets/lists of node labels) or ``'Clusters'`` (mapping cluster_label -> list of node labels). :param save_dir: Directory where output images are saved. Default is ``"results/"``. :param class_flag: If ``True``, class nodes are highlighted in yellow before other coloring. :param df_edges: Optional DataFrame with edge metrics to color edges by weight. :param layout_template: Optional layout preset. One of ``{'default', 'compact', 'vertical', 'wide'}``. :param graph_style: Optional dict of Graphviz graph attributes to override template values. :param node_style: Optional dict of Graphviz node attributes to override template values. :param edge_style: Optional dict of Graphviz edge attributes to override template values. :param fig_size: Matplotlib figure size as ``(width, height)``. :param dpi: PNG export/display resolution. :param pdf_dpi: PDF export resolution when ``export_pdf=True``. :param show: Whether to display the image via Matplotlib. Default is ``True``. :param export_pdf: If ``True``, also writes a PDF next to the PNG. :param label_mode: Label formatting strategy. One of ``{'full', 'wrapped', 'short'}``. :param readability: Graph spacing/readability preset. One of ``{'compact', 'normal', 'presentation'}``. :returns: None .. py:function:: 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: Optional[str] = None) 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 .. py:function:: change_node_color(dot, node_id: str, fillcolor: str) -> None Update a node's fill color and set an appropriate contrasting font color. :param dot: Graphviz Digraph object to modify in-place. :param node_id: Node identifier string as used in the Digraph. :param fillcolor: Hex color string (e.g. ``"#a4c2f4"``). .. py:function:: normalize_data(df: Any, attribute: str, colormap) -> Dict[Any, str] Map a numeric DataFrame column to hex color strings via a colormap. :param df: DataFrame containing at least a ``'Node'`` column and the ``attribute`` column. :param attribute: Column name whose values drive the colormap. :param colormap: Matplotlib colormap instance. :returns: Dict mapping node identifier to hex color string. .. py:function:: plot_dpg_reg(plot_name: str, dot, df: Any, df_dpg: Dict[str, Any], save_dir: str = 'examples/', attribute: Optional[str] = None, communities: bool = False, leaf_flag: bool = False, theme: str = 'dpg', palette: str = 'default') -> None Plot a regression DPG with optional node coloring by attribute or community. :param plot_name: Output base name for saved files (no extension). :param dot: Graphviz Digraph instance representing the DPG structure. :param df: DataFrame with node metrics; must include ``'Node'`` and ``'Label'`` columns. :param df_dpg: Dict of DPG metrics; used for ``'Communities'`` when ``communities=True``. :param save_dir: Directory where output images are saved. Default is ``"examples/"``. :param attribute: Optional node metric column name to color nodes by. :param communities: If True, color nodes by community index instead of a single attribute. :param leaf_flag: If True and ``attribute`` is set, exclude prediction (leaf) nodes from attribute coloring. .. py:function:: 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 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 :param normalized_constraints: Dict with structure {class_name: {feature: {min, max}}} :param feature_names: List of feature names to display :param class_colors_list: List of colors for each class :param output_path: Optional path to save the figure :param title: Title for the figure :param original_sample: Optional dict of original sample feature values :param original_class: Optional original class index (for highlighting) :param target_class: Optional target class index (for highlighting) :returns: matplotlib Figure object .. py:function:: parse_predicate_parts(label: str) -> Optional[Tuple[str, str, float]] Parse predicate labels like 'feature <= 1.23' or 'feature > 0.7'. .. py:function:: parse_feature_from_predicate(label: str) -> str Extract the feature name from a predicate label string. :param label: Predicate string such as ``"petal_length <= 2.45"``. :returns: Feature name, or the original ``label`` string if parsing fails. .. py:function:: lrc_predicate_scores(explanation, top_k: int = 10) -> Any Return top-k predicate rows ranked by Local reaching centrality. .. py:function:: plot_lrc_vs_rf_importance(explanation, model, X_df: Any, top_k: int = 10, dataset_name: str = 'Dataset', save_path: Optional[str] = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') -> Any Compare top LRC predicates and top RF feature importances side-by-side. :returns: Matplotlib figure. .. py:function:: plot_lec_vs_rf_importance(*args, **kwargs) -> Any Backward-compatible alias for a common typo. Use `plot_lrc_vs_rf_importance` instead. .. py:function:: plot_top_lrc_predicate_splits(explanation, X_df: Any, y, top_predicates: int = 5, top_features: int = 2, dataset_name: str = 'Dataset', class_names: Optional[Any] = None, save_path: Optional[str] = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') -> Optional[Any] Scatter the top-2 LRC features and overlay top-LRC predicate split lines. :returns: Matplotlib figure, or None when top features cannot be resolved. .. py:function:: sample_bc_weights(explanation, X_df: Any, top_k: int = 10) -> Any 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) :param explanation: Global DPG explanation containing ``node_metrics``. :param X_df: Feature matrix as a pandas DataFrame. :param top_k: Number of highest-BC predicate nodes to include. :returns: pandas Series indexed like ``X_df`` with one BC-derived weight per sample. .. py:function:: plot_sample_using_bc_weights(explanation, X_df: Any, y, top_k: int = 10, dataset_name: str = 'Dataset', class_names: Optional[Any] = None, save_path: Optional[str] = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') -> Any 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. .. py:function:: class_feature_predicate_counts(explanation) -> Any Compute class-vs-feature predicate frequency table from DPG communities. :returns: DataFrame indexed by class, columns as features, values as counts. .. py:function:: plot_class_feature_complexity(heat_df: Any, dataset_name: str = 'Dataset', class_names: Optional[Any] = None, top_n_features: int = 10, save_prefix: Optional[str] = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') -> Tuple[Any, Any] 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 .. py:function:: classwise_feature_bounds_from_communities(explanation) -> Any Build per-class, per-community finite/unbounded feature ranges from predicates. .. py:function:: class_feature_predicate_positions(explanation) -> Any Collect raw predicate thresholds by class/feature/operator for density overlays. .. py:function:: class_lookup_from_target_names(target_names: Optional[List[str]]) -> Dict[str, int] Build a class-name to class-index mapping from a target names list. :param 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``. .. py:function:: dataset_feature_bounds_by_class(X_df: Any, y, class_names: List[str], class_lookup: Optional[Dict[str, int]] = None) -> Any Compute empirical per-class min/max ranges for every feature in ``X_df``. :param X_df: Feature matrix with named columns. :param y: Target labels aligned with ``X_df`` rows. :param class_names: List of class name strings to compute bounds for. :param 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']``. .. py:function:: 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: Optional[Dict[str, int]] = None, predicate_positions: Optional[Any] = None, class_bounds: Optional[Any] = None, class_filter: Optional[List[str]] = None, density_tol_ratio: float = 0.03, predicate_alpha: float = 0.55, dataset_range_lw: float = 10, save_path: Optional[str] = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') -> Optional[Any] Plot DPG class bounds against empirical dataset ranges per feature. :param explanation: DPGExplanation instance. :param X_df: Feature dataframe. :param y: Class labels aligned with X_df. :param feature_cols_per_row: Number of feature panels per row block. :param class_lookup: Optional class-name to class-id mapping. :param predicate_positions: Optional precomputed output from class_feature_predicate_positions. :param class_bounds: Optional precomputed output from classwise_feature_bounds_from_communities. :param class_filter: Optional class or list of classes to render. :returns: Matplotlib figure, or None when no plottable classes exist. .. py:function:: change_edge_color(graph, source_id, target_id, new_color, new_width) Changes the color and dimension (penwidth) of a specified edge in the Graphviz Digraph. :param graph: A Graphviz Digraph object. :param source_id: The source node of the edge. :param target_id: The target node of the edge. :param new_color: The new color to be applied to the edge. :param new_width: The new penwidth (edge thickness) to be applied. :returns: None