Metadata-Version: 2.4
Name: shapleyx
Version: 0.7.0
Summary: Global sensitivity analysis with RS-HDMR — Sobol, Shapley, PAWN, and more
Author: Frederick Bennett
Author-email: frederick.bennett@des.qld.gov.au
License: MIT
Project-URL: Source, https://github.com/frbennett/shapleyx
Project-URL: Documentation, https://frbennett.github.io/shapleyx/
Project-URL: Bug Reports, https://github.com/frbennett/shapleyx/issues
Keywords: shapley sobol sensitivity analysis hdmr uncertainty quantification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: scikit-learn
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"
Requires-Dist: ipython>=7.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.2; extra == "docs"
Requires-Dist: mkdocs-material>=7.0; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: mkdocs-jupyter; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Provides-Extra: streaming
Requires-Dist: numba>=0.60; extra == "streaming"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ShapleyX — Global Sensitivity Analysis with RS-HDMR

[![PyPI](https://img.shields.io/pypi/v/shapleyx)](https://pypi.org/project/shapleyx/)
[![Python](https://img.shields.io/pypi/pyversions/shapleyx)](https://pypi.org/project/shapleyx/)
[![License](https://img.shields.io/github/license/frbennett/shapleyx)](https://github.com/frbennett/shapleyx/blob/main/LICENSE)

ShapleyX is a Python package for global sensitivity analysis using
Random Sampling High-Dimensional Model Representation (RS-HDMR).  It
builds sparse polynomial surrogate models via Automatic Relevance
Determination (ARD) regression and extracts Sobol indices, Shapley
effects, and moment-free sensitivity measures — with full support for
**correlated inputs** through Monte Carlo Shapley estimation.

## Installation

```bash
pip install shapleyx
```

To upgrade:

```bash
pip install --upgrade shapleyx
```

### From GitHub (development version)

```bash
pip install https://github.com/frbennett/shapleyx/archive/main.zip
```

## Features

- **Variance-based indices**:
  - Sobol sensitivity indices to arbitrary order
  - Shapley effects (independent inputs, via coefficient decomposition)
  - **Monte Carlo Shapley effects** for correlated inputs (Owen & Prieur 2017)
  - Owen-Shapley interaction indices
  - Total sensitivity indices

- **Moment-free measures**:
  - PAWN (density-based)
  - Delta index (moment-independent)
  - H-index (distribution-based)

- **Distribution classes for correlated inputs**:
  - `GaussianCopulaUniform` — uniform marginals with latent normal dependence
  - `MultivariateNormal` — jointly normal with analytical conditional sampling
  - `TruncatedMultivariateNormal` — per-dimension truncation bounds with Gibbs sampling

- **Computation methods**:
  - Exhaustive subset enumeration (exact, for $d \le 8$)
  - Random permutation method (scalable, for larger $d$)

- **Infrastructure**:
  - Legendre polynomial expansion on $[0,1]^d$
  - Automatic Relevance Determination (ARD) with Bayesian cross-validation
  - Bootstrap resampling for confidence intervals
  - Progress bars (via tqdm, optional) and Numba-accelerated bootstrap (optional)

## Dependencies

| Required | Optional |
|---|---|
| `numpy` | `numba` (compiled bootstrap & Legendre evals) |
| `scipy` | `tqdm` (progress bars) |
| `pandas` | |
| `matplotlib` | |
| `scikit-learn` | |

## Documentation

Full documentation is available at:
- [Documentation Home](https://frbennett.github.io/shapleyx/)
- [Quick Start Guide](https://frbennett.github.io/shapleyx/getting-started/quickstart/)
- [MC Shapley How-to](https://frbennett.github.io/shapleyx/how-to-guides/mc-shapley/)
- [Theory Background](https://frbennett.github.io/shapleyx/explanation/theory/)
- [API Reference](https://frbennett.github.io/shapleyx/reference/api/)

## Examples

Jupyter notebooks demonstrating usage:

| Notebook | Description |
|---|---|
| [Ishigami Function](https://github.com/frbennett/shapleyx/blob/main/Examples/ishigami.ipynb) | Basic RS-HDMR workflow with Sobol & Shapley |
| [MC Shapley](https://github.com/frbennett/shapleyx/blob/main/Examples/mc_shapley.ipynb) | Monte Carlo Shapley for correlated inputs |
| [Truncated Normal](https://github.com/frbennett/shapleyx/blob/main/Examples/mc_shapley_truncated_normal.ipynb) | `TruncatedMultivariateNormal` with the Ishigami function |
| [Owen Product Function](https://github.com/frbennett/shapleyx/blob/main/Examples/owen_product_function.ipynb) | Higher-dimensional example workflow |

## License

This project is licensed under the MIT License — see the [LICENSE](https://github.com/frbennett/shapleyx/blob/main/LICENSE) file for details.
