dpg.explainer#

Classes#

`DPGExplanation`	Container for global DPG outputs.
`DPGTreePathExplanation`
`DPGLocalExplanation`
`DPGExplainer`	High-level, user-friendly API for building and plotting DPG explanations.

Module Contents#

class dpg.explainer.DPGExplanation[source]#

Container for global DPG outputs.

graph: Any#

nodes: List[List[str]]#

dot: Any#

node_metrics: Any#

edge_metrics: Any#

class_boundaries: Dict[str, Any]#

communities: Dict[str, Any] | None = None#

community_threshold: float | None = None#

as_dict() → Dict[str, Any][source]#

class dpg.explainer.DPGTreePathExplanation[source]#

tree_index: int#

tree_prefix: str#

labels: List[str]#

node_ids: List[str | None]#

predicate_truths: List[bool]#

edge_exists: List[bool]#

starts_from_root: bool#

ends_in_leaf: bool#

graph_path_valid: bool#

mean_lrc: float | None = None#

mean_bc: float | None = None#

path_confidence: float | None = None#

as_dict() → Dict[str, Any][source]#

class dpg.explainer.DPGLocalExplanation[source]#

sample_id: int#

sample: List[float]#

tree_paths: List[DPGTreePathExplanation]#

graph_validated: bool#

all_trees_valid: bool#

majority_vote: str | None#

class_votes: Dict[str, int]#

path_mode: str#

sample_confidence: Dict[str, Any] | None = None#

as_dict() → Dict[str, Any][source]#

class dpg.explainer.DPGExplainer(model: Any, feature_names: Iterable[str], target_names: Iterable[str] | None = None, config_file: str = 'config.yaml', dpg_config: Dict[str, Any] | None = None)[source]#

High-level, user-friendly API for building and plotting DPG explanations.

This class wraps DecisionPredicateGraph and the metrics/visualization utilities into a cohesive workflow.

property builder: dpg.core.DecisionPredicateGraph#

fit(X: Any) → DPGExplainer[source]#: Fit the DPG structure from training data.

explain_global(X: Any | None = None, communities: bool = False, community_threshold: float = 0.2) → DPGExplanation[source]#

Build global DPG metrics and return a structured explanation object.

Parameters:

X – Optional training data. If provided, fit() is called before extracting metrics.
communities – Whether to compute cluster-based communities.
community_threshold – Threshold used by community extraction.

explain_local(sample: Any, sample_id: int = 0, X: Any | None = None, validate_graph: bool = True) → DPGLocalExplanation[source]#

Trace a single sample through every estimator and map the executed path onto the fitted DPG graph.

Parameters:

sample – One sample with the same feature dimension used to fit the model.
sample_id – Identifier to attach to the returned explanation.
X – Optional training data. If provided, fit() is called before tracing.
validate_graph – Whether to validate node and edge presence in the fitted graph.

plot_local_on_dpg(plot_name: str, local_explanation: DPGLocalExplanation | None = None, sample: Any | None = None, sample_id: int = 0, X: Any | None = None, validate_graph: bool = True, path_indices: List[int] | None = None, true_class_label: str | None = None, obtained_class_label: str | None = None, sample_metrics: Dict[str, Any] | None = None, save_dir: str = 'results/', class_flag: bool = True, layout_template: str = 'default', graph_style: Dict[str, Any] | None = None, node_style: Dict[str, Any] | None = None, edge_style: Dict[str, Any] | None = 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: str | None = None) → Any[source]#

local_path_dataframe(local_explanation: DPGLocalExplanation) → Any[source]#

Flatten a local explanation into one row per path step.

Parameters:: local_explanation – Structured local explanation returned by explain_local().
Returns:: Ordered path-step table.
Return type:: pd.DataFrame

evaluate_faithfulness(X, y_true=None, max_samples=None, weights=None, return_details=False, sample_ids=None)[source]#

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.

plot(plot_name: str, explanation: DPGExplanation | None = None, save_dir: str = 'results/', attribute: str | None = None, class_flag: bool = False, layout_template: str = 'default', graph_style: Dict[str, Any] | None = None, node_style: Dict[str, Any] | None = None, edge_style: Dict[str, Any] | None = 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: str | None = None) → None[source]#: Render a standard DPG plot.

plot_communities(plot_name: str, explanation: DPGExplanation | None = None, save_dir: str = 'results/', class_flag: bool = True, layout_template: str = 'default', graph_style: Dict[str, Any] | None = None, node_style: Dict[str, Any] | None = None, edge_style: Dict[str, Any] | None = 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: str | None = None) → None[source]#: Render a community-colored DPG plot.

plot_lrc_importance(X_df: Any, explanation: DPGExplanation | None = None, top_k: int = 10, dataset_name: str = 'Dataset', save_path: str | None = None, show: bool = True, theme: str = 'dpg', palette: str = 'default') → Any[source]#: Plot top LRC predicates vs RF feature importances.

plot_top_lrc_splits(X_df: Any, y, explanation: DPGExplanation | None = None, 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]#: Plot top-LRC split lines over the top-2 LRC feature space.

class_feature_predicate_counts(explanation: DPGExplanation | None = None, community_threshold: float = 0.2) → Any[source]#: Return class-vs-feature predicate count matrix from communities.

plot_class_feature_complexity(explanation: DPGExplanation | None = None, dataset_name: str = 'Dataset', top_n_features: int = 10, save_prefix: str | None = None, show: bool = True, community_threshold: float = 0.2, theme: str = 'dpg', palette: str = 'default') → Tuple[Any, Any][source]#: Plot community class-feature complexity using PCA-consistent class colors.

sample_bc_weights(X_df: Any, explanation: DPGExplanation | None = None, top_k: int = 10) → Any[source]#: Return the per-sample BC-derived bottleneck exposure weights.

plot_sample_using_bc_weights(X_df: Any, y, explanation: DPGExplanation | None = None, 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 set by BC-derived weights.

plot_class_bounds_vs_dataset_ranges(X_df: Any, y, explanation: DPGExplanation | None = None, dataset_name: str = 'Dataset', top_features: int = 4, feature_cols_per_row: int = 4, class_lookup: Dict[str, int] | 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, community_threshold: float = 0.2, theme: str = 'dpg', palette: str = 'default') → Any | None[source]#: Plot DPG class bounds against empirical dataset feature ranges.