Metadata-Version: 2.4
Name: shapG
Version: 0.14.1
Summary: Scalable Shapley Value Computation for Graph Data with Modular Architecture
Author-email: Chi Zhao <dandanv5@hotmail.com>
License: MIT
Project-URL: Homepage, https://github.com/vectorsss/shapG
Project-URL: Documentation, https://github.com/vectorsss/shapG#readme
Project-URL: Repository, https://github.com/vectorsss/shapG
Project-URL: Issues, https://github.com/vectorsss/shapG/issues
Keywords: shapley value,feature importance,explainable AI,graph algorithms,XAI,machine learning interpretability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=2.8
Requires-Dist: numpy
Requires-Dist: pandas>=1.3
Requires-Dist: scipy>=1.7
Requires-Dist: matplotlib>=3.4
Requires-Dist: tqdm>=4.62
Requires-Dist: scikit-learn>=1.0
Requires-Dist: tabulate>=0.8
Requires-Dist: loguru>=0.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.10; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: performance
Requires-Dist: numba>=0.56; extra == "performance"
Requires-Dist: ray>=2.0; extra == "performance"
Requires-Dist: joblib>=1.2; extra == "performance"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: nbsphinx>=0.8; extra == "docs"
Provides-Extra: examples
Requires-Dist: lightgbm>=3.3; extra == "examples"
Requires-Dist: seaborn>=0.11; extra == "examples"
Provides-Extra: all
Requires-Dist: shapG[dev,docs,examples,performance]; extra == "all"
Dynamic: license-file

# ShapG: a fast and exactly approach to approximate the Shaple value on graph

## Installation

```bash
pip install shapG
```

## Features

- Exact Shapley value computation for small to medium-sized graphs
- Fast approximate Shapley value computation for large graphs using local search
- Visualization tools for Shapley values
- Utility functions for graph generation and analysis

## Quick Start (New Modular API)

```python
import networkx as nx
from shapG import ShapGExplainer, GraphBuilder, FeatureImportanceVisualizer

# Build a graph from tabular data
builder = GraphBuilder()
G = builder.from_correlation(data, threshold=0.3)

# Compute approximate Shapley values
explainer = ShapGExplainer(depth=1, n_samples=15)
shapley_values = explainer.fit_explain(G)

# Visualize the results
viz = FeatureImportanceVisualizer()
viz.plot_importance(shapley_values)
```

## Advanced Usage

### Custom Characteristic Function

You can define a custom characteristic function:

```python
from shapG import ShapGExplainer, CustomFunction

def my_coalition_function(coalition, graph):
    subgraph = graph.subgraph(coalition)
    return nx.density(subgraph) * len(coalition)

custom_func = CustomFunction(my_coalition_function)
explainer = ShapGExplainer(characteristic_function=custom_func)
shapley_values = explainer.fit_explain(G)
```

### Customizing the Plot

```python
from shapG import FeatureImportanceVisualizer

viz = FeatureImportanceVisualizer()
fig, ax = viz.plot_importance(
    shapley_values,
    top_n=5,                    # Show only top 5 values
    style='seaborn-v0_8',       # Matplotlib style
    file_name="shapley.eps",    # Save to file
    title="Node Importance",    # Custom title
    figsize=(10, 6),            # Figure size (width, height)
    color="#2E86C1",            # Bar color
    show_values=True,           # Show values next to bars
    value_format="{:.4f}",      # Format for displayed values
    show_plot=False             # Show plot
)

# Further customize the plot using matplotlib objects
ax.set_xlabel("Contribution Score", fontsize=14)
```

## Legacy API (Deprecated)

The legacy procedural APIs (`shapG`, `shapley_value`, `graph_generator`, `plot`) are
deprecated and planned for removal in v0.15.0. Please migrate to the modular API
(`ShapGExplainer`, `ExactExplainer`, `GraphBuilder`, `FeatureImportanceVisualizer`).

## Performance Notes

Exact Shapley computation scales as O(2^n). For graphs with more than ~20 nodes,
prefer approximate explainers such as `ShapGExplainer`, `QRCSExplainer`, or
`BlockQRCSExplainer`.

## License

MIT License

## Citation

If you find this code useful in your research, please consider citing:

1. For centralities measures:
      ```
      @article{zhao2024centralitymeasuresopiniondynamics,
            title={Centrality measures and opinion dynamics in two-layer networks with replica nodes},
            author={Chi Zhao and Elena Parilina},
            year={2024},
            eprint={2406.18780},
            archivePrefix={arXiv},
            primaryClass={physics.soc-ph},
            journal={arXiv preprint arXiv:2406.18780},
            url={https://arxiv.org/abs/2406.18780},
      }
      ```
2. For the new method for explanable ai:
      ```
      @article{ZHAO2025110409,
            title = {ShapG: New feature importance method based on the Shapley value},
            journal = {Engineering Applications of Artificial Intelligence},
            volume = {148},
            pages = {110409},
            year = {2025},
            issn = {0952-1976},
            doi = {https://doi.org/10.1016/j.engappai.2025.110409},
            url = {https://www.sciencedirect.com/science/article/pii/S0952197625004099},
            author = {Chi Zhao and Jing Liu and Elena Parilina},
      }
      ```
