dpg.explainer ============= .. py:module:: dpg.explainer Classes ------- .. autoapisummary:: dpg.explainer.DPGExplanation dpg.explainer.DPGTreePathExplanation dpg.explainer.DPGLocalExplanation dpg.explainer.DPGExplainer Module Contents --------------- .. py:class:: DPGExplanation Container for global DPG outputs. .. py:attribute:: graph :type: Any .. py:attribute:: nodes :type: List[List[str]] .. py:attribute:: dot :type: Any .. py:attribute:: node_metrics :type: Any .. py:attribute:: edge_metrics :type: Any .. py:attribute:: class_boundaries :type: Dict[str, Any] .. py:attribute:: communities :type: Optional[Dict[str, Any]] :value: None .. py:attribute:: community_threshold :type: Optional[float] :value: None .. py:method:: as_dict() -> Dict[str, Any] .. py:class:: DPGTreePathExplanation .. py:attribute:: tree_index :type: int .. py:attribute:: tree_prefix :type: str .. py:attribute:: labels :type: List[str] .. py:attribute:: node_ids :type: List[Optional[str]] .. py:attribute:: predicate_truths :type: List[bool] .. py:attribute:: edge_exists :type: List[bool] .. py:attribute:: starts_from_root :type: bool .. py:attribute:: ends_in_leaf :type: bool .. py:attribute:: graph_path_valid :type: bool .. py:attribute:: mean_lrc :type: Optional[float] :value: None .. py:attribute:: mean_bc :type: Optional[float] :value: None .. py:attribute:: path_confidence :type: Optional[float] :value: None .. py:method:: as_dict() -> Dict[str, Any] .. py:class:: DPGLocalExplanation .. py:attribute:: sample_id :type: int .. py:attribute:: sample :type: List[float] .. py:attribute:: tree_paths :type: List[DPGTreePathExplanation] .. py:attribute:: graph_validated :type: bool .. py:attribute:: all_trees_valid :type: bool .. py:attribute:: majority_vote :type: Optional[str] .. py:attribute:: class_votes :type: Dict[str, int] .. py:attribute:: path_mode :type: str .. py:attribute:: sample_confidence :type: Optional[Dict[str, Any]] :value: None .. py:method:: as_dict() -> Dict[str, Any] .. py:class:: DPGExplainer(model: Any, feature_names: Iterable[str], target_names: Optional[Iterable[str]] = None, config_file: str = 'config.yaml', dpg_config: Optional[Dict[str, Any]] = None) High-level, user-friendly API for building and plotting DPG explanations. This class wraps DecisionPredicateGraph and the metrics/visualization utilities into a cohesive workflow. .. py:property:: builder :type: dpg.core.DecisionPredicateGraph .. py:method:: fit(X: Any) -> DPGExplainer Fit the DPG structure from training data. .. py:method:: explain_global(X: Optional[Any] = None, communities: bool = False, community_threshold: float = 0.2) -> DPGExplanation Build global DPG metrics and return a structured explanation object. :param X: Optional training data. If provided, fit() is called before extracting metrics. :param communities: Whether to compute cluster-based communities. :param community_threshold: Threshold used by community extraction. .. py:method:: explain_local(sample: Any, sample_id: int = 0, X: Optional[Any] = None, validate_graph: bool = True) -> DPGLocalExplanation Trace a single sample through every estimator and map the executed path onto the fitted DPG graph. :param sample: One sample with the same feature dimension used to fit the model. :param sample_id: Identifier to attach to the returned explanation. :param X: Optional training data. If provided, fit() is called before tracing. :param validate_graph: Whether to validate node and edge presence in the fitted graph. .. py:method:: plot_local_on_dpg(plot_name: str, local_explanation: Optional[DPGLocalExplanation] = None, sample: Optional[Any] = None, sample_id: int = 0, X: Optional[Any] = None, validate_graph: bool = True, path_indices: Optional[List[int]] = None, true_class_label: Optional[str] = None, obtained_class_label: Optional[str] = None, sample_metrics: Optional[Dict[str, Any]] = None, save_dir: str = 'results/', class_flag: bool = True, layout_template: str = 'default', graph_style: Optional[Dict[str, Any]] = None, node_style: Optional[Dict[str, Any]] = None, edge_style: Optional[Dict[str, Any]] = None, fig_size: Tuple[float, float] = (16, 8), dpi: int = 300, pdf_dpi: int = 600, show: bool = True, export_pdf: bool = False, theme: str = 'dpg', palette: str = 'default', label_mode: str = 'wrapped', readability: str = 'presentation', title: Optional[str] = None) -> Any .. py:method:: local_path_dataframe(local_explanation: DPGLocalExplanation) -> Any Flatten a local explanation into one row per path step. :param local_explanation: Structured local explanation returned by explain_local(). :returns: Ordered path-step table. :rtype: pd.DataFrame .. py:method:: evaluate_faithfulness(X, y_true=None, max_samples=None, weights=None, return_details=False, sample_ids=None) Evaluate local DPG explanations against the fitted black-box model. This measures output fidelity to the underlying model plus structural faithfulness diagnostics derived from local DPG traces. It does not measure ground-truth correctness unless ``y_true`` is provided, and the returned composite score is a heuristic summary, not a calibrated probability. .. py:method:: plot(plot_name: str, explanation: Optional[DPGExplanation] = None, save_dir: str = 'results/', attribute: Optional[str] = None, class_flag: bool = False, layout_template: str = 'default', graph_style: Optional[Dict[str, Any]] = None, node_style: Optional[Dict[str, Any]] = None, edge_style: Optional[Dict[str, Any]] = None, fig_size: Tuple[float, float] = (16, 8), dpi: int = 300, pdf_dpi: int = 600, show: bool = True, export_pdf: bool = False, theme: str = 'dpg', palette: str = 'default', label_mode: str = 'full', readability: str = 'normal', title: Optional[str] = None) -> None Render a standard DPG plot. .. py:method:: plot_communities(plot_name: str, explanation: Optional[DPGExplanation] = None, save_dir: str = 'results/', class_flag: bool = True, layout_template: str = 'default', graph_style: Optional[Dict[str, Any]] = None, node_style: Optional[Dict[str, Any]] = None, edge_style: Optional[Dict[str, Any]] = None, fig_size: Tuple[float, float] = (16, 8), dpi: int = 300, pdf_dpi: int = 600, show: bool = True, export_pdf: bool = False, community_threshold: float = 0.2, theme: str = 'dpg', palette: str = 'default', label_mode: str = 'wrapped', readability: str = 'presentation', title: Optional[str] = None) -> None Render a community-colored DPG plot. .. py:method:: plot_lrc_importance(X_df: Any, explanation: Optional[DPGExplanation] = None, top_k: int = 10, dataset_name: str = 'Dataset', save_path: Optional[str] = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') -> Any Plot top LRC predicates vs RF feature importances. .. py:method:: plot_top_lrc_splits(X_df: Any, y, explanation: Optional[DPGExplanation] = None, 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] Plot top-LRC split lines over the top-2 LRC feature space. .. py:method:: class_feature_predicate_counts(explanation: Optional[DPGExplanation] = None, community_threshold: float = 0.2) -> Any Return class-vs-feature predicate count matrix from communities. .. py:method:: plot_class_feature_complexity(explanation: Optional[DPGExplanation] = None, dataset_name: str = 'Dataset', top_n_features: int = 10, save_prefix: Optional[str] = None, show: bool = True, community_threshold: float = 0.2, theme: str = 'dpg', palette: str = 'default') -> Tuple[Any, Any] Plot community class-feature complexity using PCA-consistent class colors. .. py:method:: sample_bc_weights(X_df: Any, explanation: Optional[DPGExplanation] = None, top_k: int = 10) -> Any Return the per-sample BC-derived bottleneck exposure weights. .. py:method:: plot_sample_using_bc_weights(X_df: Any, y, explanation: Optional[DPGExplanation] = None, 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 set by BC-derived weights. .. py:method:: plot_class_bounds_vs_dataset_ranges(X_df: Any, y, explanation: Optional[DPGExplanation] = None, dataset_name: str = 'Dataset', top_features: int = 4, feature_cols_per_row: int = 4, class_lookup: Optional[Dict[str, int]] = 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, community_threshold: float = 0.2, theme: str = 'dpg', palette: str = 'default') -> Optional[Any] Plot DPG class bounds against empirical dataset feature ranges.