path-boost 2.1.0__tar.gz

path_boost-2.1.0/.coveragerc

@@ -0,0 +1,6 @@
+# Configuration for coverage.py
+
+[run]
+branch = True
+source = path_boost
+include = */path_boost/*

path_boost-2.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions as recommended in SPEC8:
+  # https://github.com/scientific-python/specs/pull/325
+  # At the time of writing, release critical workflows such as
+  # pypa/gh-action-pypi-publish should use hash-based versioning for security
+  # reasons. This strategy may be generalized to all other github actions
+  # in the future.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"
+    reviewers:
+      - "glemaitre"

path_boost-2.1.0/.github/workflows/deploy-gh-pages.yml

@@ -0,0 +1,34 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  deploy-gh-pages:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: prefix-dev/setup-pixi@v0.8.1
+      with:
+        pixi-version: v0.23.0
+        environments: doc
+        frozen: true
+
+    - name: Build documentation
+      run: pixi run -e doc build-doc
+
+    - name: Update the main gh-page website
+      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+      uses: peaceiris/actions-gh-pages@v4.0.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./doc/_build/html
+        commit_message: "[ci skip] ${{ github.event.head_commit.message }}"

path_boost-2.1.0/.github/workflows/lint.yml

@@ -0,0 +1,23 @@
+name: Linter
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          pixi-version: v0.23.0
+          environments: lint
+          frozen: true
+
+      - name: Run linter
+        run: pixi run -e lint lint

path_boost-2.1.0/.github/workflows/python-app.yml

@@ -0,0 +1,33 @@
+name: Unit Tests
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest, macos-12]
+        environment: [test]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          pixi-version: v0.23.0
+          environments: ${{ matrix.environment }}
+          frozen: true
+
+      - name: Run tests
+        run: pixi run -e ${{ matrix.environment }} test
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v4.6.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: scikit-learn-contrib/path_boost

path_boost-2.1.0/.gitignore

@@ -0,0 +1,78 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# scikit-learn specific
+doc/_build/
+doc/auto_examples/
+doc/modules/generated/
+doc/datasets/generated/
+
+# Distribution / packaging
+
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+doc/_build/
+doc/generated/
+doc/sg_execution_times.rst
+
+# PyBuilder
+target/
+
+.pixi
+
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# auto-generated files
+path_boost/_version.py

path_boost-2.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+    -   id: black
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.0.272
+    hooks:
+    -   id: ruff
+        args: ["--fix", "--show-source"]

path_boost-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claudio Meggio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

path_boost-2.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: path_boost
+Version: 2.1.0
+Summary: Interpretable machine learning on graph-structured data using path-based boosting.
+Author-email: Vighnesh Birodkar <vighneshbirodkar@nyu.edu>, Guillaume Lemaitre <g.lemaitre58@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Claudio-Me/extended_path_boost
+Project-URL: Issues, https://github.com/Claudio-Me/extended_path_boost/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scikit-learn>=1.4.2
+Requires-Dist: networkx>=3.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: joblib>=1.2
+Requires-Dist: scipy>=1.10
+Provides-Extra: progress
+Requires-Dist: tqdm>=4.64; extra == "progress"
+Provides-Extra: all
+Requires-Dist: tqdm>=4.64; extra == "all"
+Dynamic: license-file
+
+# Path Boost
+
+Path Boost is a Python library for interpretable machine learning on graph-structured data. It implements the PathBoost and SequentialPathBoost algorithms, which iteratively construct features based on paths in graphs and use boosting to build predictive models. The library is designed for tasks where input data consists of collections of graphs (e.g., molecules, social networks) and supports variable importance analysis for interpretability.
+
+## Features
+
+- **PathBoost**: Ensemble learning over graph paths, partitioned by anchor nodes.
+- **SequentialPathBoost**: Boosting with path-based features, iteratively expanding the feature space.
+- **Variable Importance**: Quantifies the importance of paths/features in prediction.
+- **Parallel Training**: Supports multi-core training for large datasets.
+- **Evaluation and Visualization**: Built-in tools for error tracking and variable importance plotting.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install path_boost
+```
+
+## Usage Example
+
+Below is a minimal example using the `PathBoost` model:
+
+```python
+import numpy as np
+import networkx as nx
+from sklearn.model_selection import train_test_split
+from path_boost import PathBoost
+from path_boost.utils.datasets_for_examples.generate_example_dataset import generate_synthetic_graph_dataset
+
+
+
+
+if __name__ == "__main__":
+
+    # Generate synthetic dataset
+    nx_graphs, y, true_paths, true_weights = generate_synthetic_graph_dataset()
+
+
+    list_anchor_nodes_labels = [0, 1, 2]
+
+    parameters_variable_importance: dict = {
+        'criterion': 'absolute',
+        'error_used': 'mse',
+        'use_correlation': False,
+        'normalize': True,
+    }
+
+    X_train, X_test, y_train, y_test = train_test_split(nx_graphs, y, test_size=0.25, random_state=42)
+
+    eval_set = [(X_test, y_test)]
+
+    path_boost = PathBoost(
+        n_iter=50, # Reduced for quicker example run
+        max_path_length=5,
+        learning_rate=0.1,
+        n_of_cores=1, # Set to >1 for parallel processing if desired
+        verbose=True,
+        parameters_variable_importance=parameters_variable_importance
+    )
+
+    # Fit the model
+    # anchor_nodes_label_name must correspond to the feature storing node types ('feature_0')
+    path_boost.fit(
+        X=X_train,
+        y=y_train,
+        eval_set=eval_set,
+        list_anchor_nodes_labels=list_anchor_nodes_labels,
+        anchor_nodes_label_name="feature_0" # Node types are in 'feature_0'
+    )
+    
+    print(f"Generated {len(nx_graphs)} graphs.")
+    print(f"Example y values: {y[:5]}")
+    print(f"True paths definitions: {true_paths}")
+    print(f"True path weights: {true_weights}")
+
+    path_boost.plot_training_and_eval_errors(skip_first_n_iterations=0, plot_eval_sets_error=True)
+    if path_boost.parameters_variable_importance is not None and hasattr(path_boost, 'variable_importance_'):
+        path_boost.plot_variable_importance(top_n_features=10)
+    else:
+        print("Variable importance not computed or available.")
+
+    print("Example run finished.")
+
+```
+
+## API Overview
+
+### PathBoost
+
+- `fit(X, y, anchor_nodes_label_name, list_anchor_nodes_labels, eval_set=None)`
+- `predict(X)`
+- `predict_step_by_step(X)`
+- `evaluate(X, y)`
+- `plot_training_and_eval_errors(skip_first_n_iterations=True)`
+- `plot_variable_importance()`
+- **Attributes:**
+  - `train_mse_`: Training error (MSE) at each iteration
+  - `mse_eval_set_`: Evaluation set error (MSE) at each iteration (if `eval_set` is provided)
+  - `variable_importance_`: Variable/path importance scores (if enabled)
+  - `is_fitted_`: Whether the model is fitted
+  - `models_list_`: List of fitted SequentialPathBoost models (one per anchor node)
+  - (Each SequentialPathBoost in `models_list_` exposes the attributes below)
+
+### SequentialPathBoost
+
+- `fit(X, y, list_anchor_nodes_labels, name_of_label_attribute, eval_set=None)`
+- `predict(X)`
+- `predict_step_by_step(X)`
+- `evaluate(X, y)`
+- `plot_training_and_eval_errors(skip_first_n_iterations=True)`
+- `plot_variable_importance()`
+- **Attributes:**
+  - `train_mse_`: Training error (MSE) at each iteration
+  - `train_mae_`: Training MAE at each iteration
+  - `eval_sets_mse_`: Evaluation set error (MSE) at each iteration (if `eval_set` is provided)
+  - `eval_sets_mae_`: Evaluation set MAE at each iteration (if `eval_set` is provided)
+  - `variable_importance_`: Variable/path importance scores (if enabled)
+  - `paths_selected_by_epb_`: Set of selected paths during boosting
+  - `columns_names_`: Names of EBM columns/features used
+  - `is_fitted_`: Whether the model is fitted
+
+## Requirements
+
+- Python 3.10+
+- numpy
+- pandas
+- scikit-learn
+- networkx
+- matplotlib
+
+(See `requirements.txt` for the full list.)
+
+## Citation
+
+If you use this library in your research, please cite the corresponding paper (add citation here).
+
+## License
+
+BSD 3-Clause License

path_boost-2.1.0/README.md

@@ -0,0 +1,141 @@
+# Path Boost
+
+Path Boost is a Python library for interpretable machine learning on graph-structured data. It implements the PathBoost and SequentialPathBoost algorithms, which iteratively construct features based on paths in graphs and use boosting to build predictive models. The library is designed for tasks where input data consists of collections of graphs (e.g., molecules, social networks) and supports variable importance analysis for interpretability.
+
+## Features
+
+- **PathBoost**: Ensemble learning over graph paths, partitioned by anchor nodes.
+- **SequentialPathBoost**: Boosting with path-based features, iteratively expanding the feature space.
+- **Variable Importance**: Quantifies the importance of paths/features in prediction.
+- **Parallel Training**: Supports multi-core training for large datasets.
+- **Evaluation and Visualization**: Built-in tools for error tracking and variable importance plotting.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install path_boost
+```
+
+## Usage Example
+
+Below is a minimal example using the `PathBoost` model:
+
+```python
+import numpy as np
+import networkx as nx
+from sklearn.model_selection import train_test_split
+from path_boost import PathBoost
+from path_boost.utils.datasets_for_examples.generate_example_dataset import generate_synthetic_graph_dataset
+
+
+
+
+if __name__ == "__main__":
+
+    # Generate synthetic dataset
+    nx_graphs, y, true_paths, true_weights = generate_synthetic_graph_dataset()
+
+
+    list_anchor_nodes_labels = [0, 1, 2]
+
+    parameters_variable_importance: dict = {
+        'criterion': 'absolute',
+        'error_used': 'mse',
+        'use_correlation': False,
+        'normalize': True,
+    }
+
+    X_train, X_test, y_train, y_test = train_test_split(nx_graphs, y, test_size=0.25, random_state=42)
+
+    eval_set = [(X_test, y_test)]
+
+    path_boost = PathBoost(
+        n_iter=50, # Reduced for quicker example run
+        max_path_length=5,
+        learning_rate=0.1,
+        n_of_cores=1, # Set to >1 for parallel processing if desired
+        verbose=True,
+        parameters_variable_importance=parameters_variable_importance
+    )
+
+    # Fit the model
+    # anchor_nodes_label_name must correspond to the feature storing node types ('feature_0')
+    path_boost.fit(
+        X=X_train,
+        y=y_train,
+        eval_set=eval_set,
+        list_anchor_nodes_labels=list_anchor_nodes_labels,
+        anchor_nodes_label_name="feature_0" # Node types are in 'feature_0'
+    )
+    
+    print(f"Generated {len(nx_graphs)} graphs.")
+    print(f"Example y values: {y[:5]}")
+    print(f"True paths definitions: {true_paths}")
+    print(f"True path weights: {true_weights}")
+
+    path_boost.plot_training_and_eval_errors(skip_first_n_iterations=0, plot_eval_sets_error=True)
+    if path_boost.parameters_variable_importance is not None and hasattr(path_boost, 'variable_importance_'):
+        path_boost.plot_variable_importance(top_n_features=10)
+    else:
+        print("Variable importance not computed or available.")
+
+    print("Example run finished.")
+
+```
+
+## API Overview
+
+### PathBoost
+
+- `fit(X, y, anchor_nodes_label_name, list_anchor_nodes_labels, eval_set=None)`
+- `predict(X)`
+- `predict_step_by_step(X)`
+- `evaluate(X, y)`
+- `plot_training_and_eval_errors(skip_first_n_iterations=True)`
+- `plot_variable_importance()`
+- **Attributes:**
+  - `train_mse_`: Training error (MSE) at each iteration
+  - `mse_eval_set_`: Evaluation set error (MSE) at each iteration (if `eval_set` is provided)
+  - `variable_importance_`: Variable/path importance scores (if enabled)
+  - `is_fitted_`: Whether the model is fitted
+  - `models_list_`: List of fitted SequentialPathBoost models (one per anchor node)
+  - (Each SequentialPathBoost in `models_list_` exposes the attributes below)
+
+### SequentialPathBoost
+
+- `fit(X, y, list_anchor_nodes_labels, name_of_label_attribute, eval_set=None)`
+- `predict(X)`
+- `predict_step_by_step(X)`
+- `evaluate(X, y)`
+- `plot_training_and_eval_errors(skip_first_n_iterations=True)`
+- `plot_variable_importance()`
+- **Attributes:**
+  - `train_mse_`: Training error (MSE) at each iteration
+  - `train_mae_`: Training MAE at each iteration
+  - `eval_sets_mse_`: Evaluation set error (MSE) at each iteration (if `eval_set` is provided)
+  - `eval_sets_mae_`: Evaluation set MAE at each iteration (if `eval_set` is provided)
+  - `variable_importance_`: Variable/path importance scores (if enabled)
+  - `paths_selected_by_epb_`: Set of selected paths during boosting
+  - `columns_names_`: Names of EBM columns/features used
+  - `is_fitted_`: Whether the model is fitted
+
+## Requirements
+
+- Python 3.10+
+- numpy
+- pandas
+- scikit-learn
+- networkx
+- matplotlib
+
+(See `requirements.txt` for the full list.)
+
+## Citation
+
+If you use this library in your research, please cite the corresponding paper (add citation here).
+
+## License
+
+BSD 3-Clause License