DPG 0.2.0__tar.gz → 0.3.0__tar.gz

{dpg-0.2.0 → dpg-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dpg
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Python library for extracting Decision Predicate Graphs and global explanations from ensemble models.
 License: MIT
 License-File: LICENSE
@@ -54,12 +54,12 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue.svg)](pyproject.toml)
-[![PyPI](https://img.shields.io/pypi/v/dpg.svg)](https://pypi.org/project/dpg/)
 [![Build Status](https://github.com/Meta-Group/DPG/actions/workflows/ci.yml/badge.svg)](https://github.com/Meta-Group/DPG/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/dpg/badge/?version=latest)](https://dpg.readthedocs.io/en/latest/)
 
-| ![DPG logo](https://github.com/Meta-Group/DPG/blob/main/DPG.png) |
-|:--:|
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/DPG.png" alt="DPG logo" width="300">
+</p>
 
 
 DPG is a model-agnostic framework for global and local explanation of tree-based ensemble models.
@@ -72,7 +72,9 @@ insightful points. DPG enables graph-based evaluations and the identification of
 towards facilitating comparisons between features and their associated values while offering insights
 into the entire model. DPG provides descriptive metrics that enhance the understanding of the
 decisions inherent in the model, offering valuable insights.
-![DPG overview](https://github.com/Meta-Group/DPG/blob/main/image.png)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/image.png" width="600" />
+</p>
 
 ---
 
@@ -98,7 +100,9 @@ The concept behind DPG is to convert a generic tree-based ensemble model for cla
 - Nodes represent predicates, i.e., the feature-value associations present in each node of every tree;
 - Edges denote the frequency with which these predicates are satisfied during the model training phase by the samples of the dataset.
 
-![DPG example](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example.png?raw=true)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example.png" width="600" />
+</p>
 
 ## Metrics
 The graph-based nature of DPG provides significant enhancements in the direction of a complete mapping of the ensemble structure.
@@ -112,7 +116,7 @@ The graph-based nature of DPG provides significant enhancements in the direction
 
 |Constraints | Betweenness centrality | Local reaching centrality | Community|
 |------------|------------|--------------|--------------------|
-![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_constraints.png) | ![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_bc.png) | ![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_lrc.png) | ![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_community.png) |
+![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_constraints.png) | ![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_bc.png) | ![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_lrc.png) | ![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_community.png) |
 |Constraints(Class 1) = val3 < F1 ≤ val1, F2 ≤ val2 | BC(F2 ≤ val2) = 4/24 | LRC(F1 ≤ val1) = 6 / 7 | Community(Class 1) = F1 ≤ val1, F2 ≤ val2 |
 
 ---
@@ -220,6 +224,7 @@ explainer = DPGExplainer(
             },
             "graph_construction": {
                 "mode": "execution_trace",  # or "aggregated_transitions"
+                "context_order": 1,           # 1, an integer > 1, or "auto"
             },
         }
     },
@@ -229,6 +234,31 @@ explainer = DPGExplainer(
 - `"aggregated_transitions"`: current default behavior; filters path variants first, then discovers the DPG.
 - `"execution_trace"`: builds directly from raw traces and filters edges instead of whole-path variants when `perc_var > 0`.
 
+`context_order` controls predicate identity in `execution_trace` mode. `1`
+preserves the legacy graph exactly; an order greater than one uses the last k
+executed predicates as context and keeps one sink per class. `"auto"` resolves
+the smallest order for which every pooled graph path is supported by an
+observed execution trace, including recombinations that only appear after
+multiple hops. Orders greater than one require `mode: "execution_trace"`.
+`context_order="auto"` also requires `execution_trace`; in
+`aggregated_transitions` mode context resolution is not applied.
+
+A phantom path is a multi-hop path assembled by pooling edges from different
+tree executions even though no single execution produced it. DPG-k removes
+these recombinations at the resolved context order while retaining one graph.
+The effective order and each node's context are available through
+`get_context_order()` and `get_node_context(node)`.
+
+**Regression scope (0.3.0):** `context_order` builds without raising for
+regressors (regression leaves, labeled `"Pred <value>"`, are treated as
+terminal sinks just like class leaves), but "one sink per output" is not a
+defined guarantee for regression the way it is for classification: two
+leaves collapse into the same sink only when their rounded values coincide,
+which is an artifact of label rounding, not a modeled invariant. A
+principled regression sink policy is deferred past 0.3.0. `class_boundaries`
+and `communities` remain classifier-only; calling `explain_global`
+with `communities=True` on a regressor raises a clear `ValueError`.
+
 #### Minimal local workflow
 
 ```python
@@ -314,8 +344,8 @@ Important:
 
 ## CLI scripts
 The library contains two different scripts to apply DPG:
-- `run_dpg_standard.py`: with this script it is possible to test DPG on a standard classification dataset provided by `sklearn` such as `iris`, `digits`, `wine`, `breast cancer`, and `diabetes`.
-- `run_dpg_custom.py`: with this script it is possible to apply DPG to your classification dataset, specifying the target class.
+- `examples/run_dpg_standard.py`: with this script it is possible to test DPG on a standard classification dataset provided by `sklearn` such as `iris`, `digits`, `wine`, `breast cancer`, and `diabetes`.
+- `examples/run_dpg_custom.py`: with this script it is possible to apply DPG to your classification dataset, specifying the target class.
 
 ### Implementation notes
 The library also contains two other essential scripts:
@@ -323,14 +353,17 @@ The library also contains two other essential scripts:
 - `visualizer.py` contains the functions used to manage the visualization of DPG.
 
 ### Output
-The DPG output, through `run_dpg_standard.py` or `run_dpg_custom.py`, produces several files:
+The DPG output, through `examples/run_dpg_standard.py` or `examples/run_dpg_custom.py`, produces several files:
 - the visualization of DPG in a dedicated environment, which can be zoomed and saved;
 - a `.txt` file containing the DPG metrics;
 - a `.csv` file containing the information about all the nodes of the DPG and their associated metrics;
 - a `.txt` file containing the Random Forest statistics (accuracy, confusion matrix, classification report)
 
 ### CLI parameter reference
-Usage: `python run_dpg_standard.py --dataset <dataset_name> --n_learners <integer_number> --pv <threshold_value> --t <integer_number> --model_name <str_model_name> --dir <save_dir_path> --plot --save_plot_dir <save_plot_dir_path> --attribute <attribute> --communities --clusters --threshold_clusters <float> --class_flag --seed <int>`
+Usage: `dpg --dataset <dataset_name> --n_learners <integer_number> --pv <threshold_value> --t <integer_number> --model_name <str_model_name> --dir <save_dir_path> --plot --save_plot_dir <save_plot_dir_path> --attribute <attribute> --communities --clusters --threshold_clusters <float> --class_flag --seed <int>`
+
+After installing DPG, the `dpg` command is the packaged equivalent of
+`python examples/run_dpg_standard.py`.
 Where:
 - `dataset` is the name of the standard classification `sklearn` dataset to be analyzed;
 - `n_learners` is the number of base learners for the ensemble model;
@@ -357,23 +390,29 @@ Where:
   
 Disclaimer: `attribute`, `communities`, and `clusters` are mutually exclusive: DPG supports just one visualization mode at a time.
 
-The usage of `run_dpg_custom.py` is similar, but it requires another parameter:
+The usage of `examples/run_dpg_custom.py` is similar, but it requires another parameter:
 - `target_column`, which is the name of the column to be used as the target variable;
 - while `ds` is the path of the directory where the dataset is.
 
-### Example `run_dpg_standard.py`
+### Example `examples/run_dpg_standard.py`
 Some examples can be appreciated in the `examples` folder: https://github.com/Meta-Group/DPG/tree/main/examples
 
 In particular, the following DPG is obtained by transforming a Random Forest with 5 base learners, trained on Iris dataset.
-The used command is `python run_dpg_standard.py --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples`.
-![Iris DPG](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/iris_bl5_perc0.001_dec2.png)
+The used command is `dpg --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/iris_bl5_perc0.001_dec2.png" width="800" />
+</p>
 
 The following visualizations are obtained using the same parameters as the previous example, but they show two different metrics: _Community_ and _Betweenness centrality_.
-The used command for showing communities is `python run_dpg_standard.py --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --communities`.
-![Iris communities](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/iris_bl5_perc0.001_dec2_communities.png)
-
-The used command for showing a specific property is `python run_dpg_standard.py --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --attribute "Betweenness centrality" --class_flag`.
-![Iris betweenness centrality](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/iris_bl5_perc0.001_dec2_Betweennesscentrality.png)
+The used command for showing communities is `dpg --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --communities`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/iris_bl5_perc0.001_dec2_communities.png" width="800" />
+</p>
+
+The used command for showing a specific property is `dpg --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --attribute "Betweenness centrality" --class_flag`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/iris_bl5_perc0.001_dec2_Betweennesscentrality.png" width="800" />
+</p>
 
 ***
 ## Citation

{dpg-0.2.0 → dpg-0.3.0}/README.md

@@ -2,12 +2,12 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue.svg)](pyproject.toml)
-[![PyPI](https://img.shields.io/pypi/v/dpg.svg)](https://pypi.org/project/dpg/)
 [![Build Status](https://github.com/Meta-Group/DPG/actions/workflows/ci.yml/badge.svg)](https://github.com/Meta-Group/DPG/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/dpg/badge/?version=latest)](https://dpg.readthedocs.io/en/latest/)
 
-| ![DPG logo](https://github.com/Meta-Group/DPG/blob/main/DPG.png) |
-|:--:|
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/DPG.png" alt="DPG logo" width="300">
+</p>
 
 
 DPG is a model-agnostic framework for global and local explanation of tree-based ensemble models.
@@ -20,7 +20,9 @@ insightful points. DPG enables graph-based evaluations and the identification of
 towards facilitating comparisons between features and their associated values while offering insights
 into the entire model. DPG provides descriptive metrics that enhance the understanding of the
 decisions inherent in the model, offering valuable insights.
-![DPG overview](https://github.com/Meta-Group/DPG/blob/main/image.png)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/image.png" width="600" />
+</p>
 
 ---
 
@@ -46,7 +48,9 @@ The concept behind DPG is to convert a generic tree-based ensemble model for cla
 - Nodes represent predicates, i.e., the feature-value associations present in each node of every tree;
 - Edges denote the frequency with which these predicates are satisfied during the model training phase by the samples of the dataset.
 
-![DPG example](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example.png?raw=true)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example.png" width="600" />
+</p>
 
 ## Metrics
 The graph-based nature of DPG provides significant enhancements in the direction of a complete mapping of the ensemble structure.
@@ -60,7 +64,7 @@ The graph-based nature of DPG provides significant enhancements in the direction
 
 |Constraints | Betweenness centrality | Local reaching centrality | Community|
 |------------|------------|--------------|--------------------|
-![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_constraints.png) | ![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_bc.png) | ![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_lrc.png) | ![](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/example_community.png) |
+![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_constraints.png) | ![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_bc.png) | ![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_lrc.png) | ![](https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/example_community.png) |
 |Constraints(Class 1) = val3 < F1 ≤ val1, F2 ≤ val2 | BC(F2 ≤ val2) = 4/24 | LRC(F1 ≤ val1) = 6 / 7 | Community(Class 1) = F1 ≤ val1, F2 ≤ val2 |
 
 ---
@@ -168,6 +172,7 @@ explainer = DPGExplainer(
             },
             "graph_construction": {
                 "mode": "execution_trace",  # or "aggregated_transitions"
+                "context_order": 1,           # 1, an integer > 1, or "auto"
             },
         }
     },
@@ -177,6 +182,31 @@ explainer = DPGExplainer(
 - `"aggregated_transitions"`: current default behavior; filters path variants first, then discovers the DPG.
 - `"execution_trace"`: builds directly from raw traces and filters edges instead of whole-path variants when `perc_var > 0`.
 
+`context_order` controls predicate identity in `execution_trace` mode. `1`
+preserves the legacy graph exactly; an order greater than one uses the last k
+executed predicates as context and keeps one sink per class. `"auto"` resolves
+the smallest order for which every pooled graph path is supported by an
+observed execution trace, including recombinations that only appear after
+multiple hops. Orders greater than one require `mode: "execution_trace"`.
+`context_order="auto"` also requires `execution_trace`; in
+`aggregated_transitions` mode context resolution is not applied.
+
+A phantom path is a multi-hop path assembled by pooling edges from different
+tree executions even though no single execution produced it. DPG-k removes
+these recombinations at the resolved context order while retaining one graph.
+The effective order and each node's context are available through
+`get_context_order()` and `get_node_context(node)`.
+
+**Regression scope (0.3.0):** `context_order` builds without raising for
+regressors (regression leaves, labeled `"Pred <value>"`, are treated as
+terminal sinks just like class leaves), but "one sink per output" is not a
+defined guarantee for regression the way it is for classification: two
+leaves collapse into the same sink only when their rounded values coincide,
+which is an artifact of label rounding, not a modeled invariant. A
+principled regression sink policy is deferred past 0.3.0. `class_boundaries`
+and `communities` remain classifier-only; calling `explain_global`
+with `communities=True` on a regressor raises a clear `ValueError`.
+
 #### Minimal local workflow
 
 ```python
@@ -262,8 +292,8 @@ Important:
 
 ## CLI scripts
 The library contains two different scripts to apply DPG:
-- `run_dpg_standard.py`: with this script it is possible to test DPG on a standard classification dataset provided by `sklearn` such as `iris`, `digits`, `wine`, `breast cancer`, and `diabetes`.
-- `run_dpg_custom.py`: with this script it is possible to apply DPG to your classification dataset, specifying the target class.
+- `examples/run_dpg_standard.py`: with this script it is possible to test DPG on a standard classification dataset provided by `sklearn` such as `iris`, `digits`, `wine`, `breast cancer`, and `diabetes`.
+- `examples/run_dpg_custom.py`: with this script it is possible to apply DPG to your classification dataset, specifying the target class.
 
 ### Implementation notes
 The library also contains two other essential scripts:
@@ -271,14 +301,17 @@ The library also contains two other essential scripts:
 - `visualizer.py` contains the functions used to manage the visualization of DPG.
 
 ### Output
-The DPG output, through `run_dpg_standard.py` or `run_dpg_custom.py`, produces several files:
+The DPG output, through `examples/run_dpg_standard.py` or `examples/run_dpg_custom.py`, produces several files:
 - the visualization of DPG in a dedicated environment, which can be zoomed and saved;
 - a `.txt` file containing the DPG metrics;
 - a `.csv` file containing the information about all the nodes of the DPG and their associated metrics;
 - a `.txt` file containing the Random Forest statistics (accuracy, confusion matrix, classification report)
 
 ### CLI parameter reference
-Usage: `python run_dpg_standard.py --dataset <dataset_name> --n_learners <integer_number> --pv <threshold_value> --t <integer_number> --model_name <str_model_name> --dir <save_dir_path> --plot --save_plot_dir <save_plot_dir_path> --attribute <attribute> --communities --clusters --threshold_clusters <float> --class_flag --seed <int>`
+Usage: `dpg --dataset <dataset_name> --n_learners <integer_number> --pv <threshold_value> --t <integer_number> --model_name <str_model_name> --dir <save_dir_path> --plot --save_plot_dir <save_plot_dir_path> --attribute <attribute> --communities --clusters --threshold_clusters <float> --class_flag --seed <int>`
+
+After installing DPG, the `dpg` command is the packaged equivalent of
+`python examples/run_dpg_standard.py`.
 Where:
 - `dataset` is the name of the standard classification `sklearn` dataset to be analyzed;
 - `n_learners` is the number of base learners for the ensemble model;
@@ -305,23 +338,29 @@ Where:
   
 Disclaimer: `attribute`, `communities`, and `clusters` are mutually exclusive: DPG supports just one visualization mode at a time.
 
-The usage of `run_dpg_custom.py` is similar, but it requires another parameter:
+The usage of `examples/run_dpg_custom.py` is similar, but it requires another parameter:
 - `target_column`, which is the name of the column to be used as the target variable;
 - while `ds` is the path of the directory where the dataset is.
 
-### Example `run_dpg_standard.py`
+### Example `examples/run_dpg_standard.py`
 Some examples can be appreciated in the `examples` folder: https://github.com/Meta-Group/DPG/tree/main/examples
 
 In particular, the following DPG is obtained by transforming a Random Forest with 5 base learners, trained on Iris dataset.
-The used command is `python run_dpg_standard.py --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples`.
-![Iris DPG](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/iris_bl5_perc0.001_dec2.png)
+The used command is `dpg --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/iris_bl5_perc0.001_dec2.png" width="800" />
+</p>
 
 The following visualizations are obtained using the same parameters as the previous example, but they show two different metrics: _Community_ and _Betweenness centrality_.
-The used command for showing communities is `python run_dpg_standard.py --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --communities`.
-![Iris communities](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/iris_bl5_perc0.001_dec2_communities.png)
-
-The used command for showing a specific property is `python run_dpg_standard.py --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --attribute "Betweenness centrality" --class_flag`.
-![Iris betweenness centrality](https://github.com/Meta-Group/DPG/blob/main/dpg_image_examples/iris_bl5_perc0.001_dec2_Betweennesscentrality.png)
+The used command for showing communities is `dpg --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --communities`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/iris_bl5_perc0.001_dec2_communities.png" width="800" />
+</p>
+
+The used command for showing a specific property is `dpg --dataset iris --n_learners 5 --pv 0.001 --t 2 --dir examples --plot --save_plot_dir examples --attribute "Betweenness centrality" --class_flag`.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Meta-Group/DPG/main/dpg_image_examples/iris_bl5_perc0.001_dec2_Betweennesscentrality.png" width="800" />
+</p>
 
 ***
 ## Citation

{dpg-0.2.0 → dpg-0.3.0}/dpg/__init__.py

@@ -13,6 +13,7 @@ from .visualizer import (
     classwise_feature_bounds_from_communities,
     plot_class_feature_complexity,
     plot_dpg,
+    plot_dpg_communities,
     plot_dpg_class_bounds_vs_dataset_feature_ranges,
     plot_dpg_constraints_overview,
     plot_dpg_local_paths_aggregate,
@@ -35,6 +36,7 @@ __all__ = [
     "DPG_OLIVE_CLASS_PALETTE",
     "resolve_theme_context",
     "plot_dpg",
+    "plot_dpg_communities",
     "plot_dpg_local_paths_aggregate",
     "plot_dpg_reg",
     "plot_dpg_constraints_overview",

dpg-0.3.0/dpg/cli.py

@@ -0,0 +1,96 @@
+"""Packaged command-line interface for the standard DPG demonstration."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Sequence
+
+from .sklearn_dpg import test_dpg
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the parser used by the installed ``dpg`` command."""
+    parser = argparse.ArgumentParser(
+        description="Train a sklearn tree ensemble and export its DPG metrics."
+    )
+    parser.add_argument(
+        "--dataset",
+        "--ds",
+        dest="dataset",
+        default="iris",
+        help="sklearn dataset name or path to a CSV file",
+    )
+    parser.add_argument(
+        "--target_column",
+        default=None,
+        help="target column when --dataset points to a CSV file",
+    )
+    parser.add_argument("--n_learners", "--l", dest="n_learners", type=int, default=5)
+    parser.add_argument("--model_name", default="RandomForestClassifier")
+    parser.add_argument("--dir", default="examples/results", help="output directory")
+    parser.add_argument("--plot", action="store_true")
+    parser.add_argument("--save_plot_dir", default="examples/results")
+    parser.add_argument("--attribute", default=None)
+    parser.add_argument("--communities", action="store_true")
+    parser.add_argument("--clusters", action="store_true")
+    parser.add_argument("--threshold_clusters", type=float, default=None)
+    parser.add_argument("--t", type=int, default=3, help="threshold decimal precision")
+    parser.add_argument("--class_flag", action="store_true")
+    parser.add_argument("--seed", type=int, default=160898)
+    parser.add_argument(
+        "--pv",
+        type=float,
+        default=1e-9,
+        help="minimum path frequency proportion",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the standard DPG workflow and write metrics to disk."""
+    args = build_parser().parse_args(argv)
+    output_dir = Path(args.dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    result = test_dpg(
+        datasets=args.dataset,
+        target_column=args.target_column,
+        n_learners=args.n_learners,
+        perc_var=args.pv,
+        decimal_threshold=args.t,
+        n_jobs=-1,
+        model_name=args.model_name,
+        file_name=str(output_dir / f"{Path(args.dataset).stem}_seed{args.seed}_stats.txt"),
+        plot=args.plot,
+        save_plot_dir=args.save_plot_dir,
+        attribute=args.attribute,
+        communities=args.communities,
+        clusters_flag=args.clusters,
+        threshold_clusters=args.threshold_clusters,
+        class_flag=args.class_flag,
+        seed=args.seed,
+    )
+    # ``test_dpg`` signals "insufficient nodes for DPG analysis" with
+    # ``(None, None)`` rather than a bare ``None``; guard on shape, not identity.
+    if result is None or len(result) != 6:
+        return 1
+
+    df, df_edges, graph_metrics, clusters, node_prob, confidence = result
+    stem = Path(args.dataset).stem
+    df.to_csv(output_dir / f"{stem}_seed{args.seed}_node_metrics.csv", index=False)
+    df_edges.to_csv(output_dir / f"{stem}_seed{args.seed}_edge_metrics.csv", index=False)
+    with (output_dir / f"{stem}_seed{args.seed}_dpg_metrics.txt").open("w", encoding="utf-8") as handle:
+        for key, value in graph_metrics.items():
+            handle.write(f"{key}: {value}\n")
+
+    if clusters is not None:
+        with (output_dir / f"{stem}_seed{args.seed}_clusters.txt").open("w", encoding="utf-8") as handle:
+            handle.write(f"Clusters: {clusters}\n")
+            handle.write(f"Probability: {node_prob}\n")
+            handle.write(f"Confidence: {confidence}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dpg-0.3.0/dpg/context_order.py

@@ -0,0 +1,114 @@
+"""Fast resolution of the smallest context order without path enumeration."""
+
+from collections import defaultdict
+import math
+from typing import Iterable, Sequence
+
+
+def _node_windows(sequence: Sequence[str], k: int | float) -> list[object]:
+    """Represent a trace as contextual predicate nodes and class sinks."""
+    nodes: list[object] = []
+    for index, label in enumerate(sequence):
+        if str(label).startswith(("Class ", "Pred ")):
+            nodes.append(("sink", str(label)))
+            continue
+        if math.isinf(k):
+            context = tuple(sequence[: index + 1])
+        else:
+            context = tuple(sequence[max(0, index - int(k) + 1) : index + 1])
+        nodes.append(("ctx", context))
+    return nodes
+
+
+def path_violations(traces: Iterable[Sequence[str]], k: int | float) -> int:
+    """Count pooled-graph paths that are not observed trace prefixes.
+
+    A pooled DFG can be locally consistent while still recombining after
+    several hops.  For example, observing ``A-B-C-D`` and ``X-B-C-E`` gives
+    every adjacent transition a witness, but also creates the unobserved
+    path ``A-B-C-E``.  This check builds a trie of observed contextual traces,
+    computes each prefix state's future signature bottom-up, and verifies
+    that states merged by the same contextual node have the same future
+    language.  It avoids both exponential simple-path enumeration and the
+    potentially large graph-by-trie product.
+
+    The returned value is a diagnostic count, not a count of all phantom
+    paths.  A value of zero is the useful acceptance condition: every graph
+    path is represented by an observed trace.
+    """
+    materialized = [tuple(trace) for trace in traces if trace]
+    if not materialized:
+        return 0
+
+    trie_children: list[dict[object, int]] = [{}]
+    trie_terminal: set[int] = set()
+    trie_context: list[object | None] = [None]
+
+    for sequence in materialized:
+        nodes = _node_windows(sequence, k)
+        trie_node = 0
+        for node in nodes:
+            next_node = trie_children[trie_node].get(node)
+            if next_node is None:
+                next_node = len(trie_children)
+                trie_children[trie_node][node] = next_node
+                trie_children.append({})
+                trie_context.append(node)
+            trie_node = next_node
+        trie_terminal.add(trie_node)
+
+    signatures: list[tuple[bool, tuple[tuple[object, object], ...]]] = [
+        (False, ())
+    ] * len(trie_children)
+    for trie_node in range(len(trie_children) - 1, -1, -1):
+        children = tuple(
+            sorted(
+                (
+                    (child_label, signatures[child_node])
+                    for child_label, child_node in trie_children[trie_node].items()
+                ),
+                key=repr,
+            )
+        )
+        signatures[trie_node] = (trie_node in trie_terminal, children)
+
+    future_by_context: defaultdict[object, set[tuple[bool, tuple]]] = defaultdict(set)
+    for trie_node in range(1, len(trie_children)):
+        context = trie_context[trie_node]
+        assert context is not None
+        future_by_context[context].add(signatures[trie_node])
+
+    return sum(max(0, len(futures) - 1) for futures in future_by_context.values())
+
+
+def resolve_context_order(
+    traces: Iterable[Sequence[str]], max_k: int | None = None
+) -> tuple[int | float, dict[int | float, int]]:
+    """Return the smallest order with no global trace recombination.
+
+    ``max_k`` defaults to the longest observed trace.  At that order every
+    observed prefix is distinct, which is a proof-based bound rather than a
+    user-facing cap.  When a caller supplies a smaller cap, resolution must
+    still succeed within that cap; otherwise ``ValueError`` is raised instead
+    of returning an order whose history still contains violations.
+    """
+    if max_k is not None and (
+        isinstance(max_k, bool) or not isinstance(max_k, int) or max_k < 1
+    ):
+        raise ValueError("max_k must be a positive integer or None")
+
+    materialized = [tuple(trace) for trace in traces if trace]
+    if not materialized:
+        return 1, {1: 0}
+    if max_k is None:
+        max_k = max(len(trace) for trace in materialized)
+
+    history: dict[int | float, int] = {}
+    for k in range(1, max_k + 1):
+        violations = path_violations(materialized, k)
+        history[k] = violations
+        if violations == 0:
+            return k, history
+    raise ValueError(
+        f"no context order <= max_k={max_k} eliminates all global trace violations"
+    )