Metadata-Version: 2.4
Name: signxai2
Version: 0.14.1
Summary: A comprehensive explainable AI library supporting both TensorFlow and PyTorch with unified API and advanced XAI methods including SIGN, LRP, and Grad-CAM. Authored by Nils Gumpfer, Jana Fischer and Alexander Paul.
Author-email: TimeXAIgroup <nils.gumpfer@kite.thm.de>
Maintainer-email: Nils Gumpfer <nils.gumpfer@kite.thm.de>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://www.thm.de/mnd/jennifer-hannig/timexai-erklaerbare-kuenstliche-intelligenz-fuer-zeitreihen
Project-URL: Documentation, https://TimeXAIgroup.github.io/signxai2/index.html
Project-URL: Repository, https://github.com/TimeXAIgroup/signxai2.git
Project-URL: Bug Reports, https://github.com/TimeXAIgroup/signxai2/issues
Project-URL: Changelog, https://github.com/TimeXAIgroup/signxai2/blob/main/CHANGELOG.md
Project-URL: Publication, https://www.sciencedirect.com/science/article/pii/S1566253523001999?via%3Dihub
Keywords: explainable ai,xai,interpretability,machine learning,deep learning,tensorflow,pytorch,lrp,grad-cam,sign,attribution,saliency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Classifier: Framework :: Jupyter
Requires-Python: <3.11,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==1.26.4
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pillow>=8.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: setuptools~=68.2.2
Requires-Dist: version-parser>=1.0.1
Requires-Dist: protobuf<=3.20.3
Requires-Dist: scikit-learn~=1.5.0
Requires-Dist: scikit-image>=0.19.0
Requires-Dist: jupyter>=1.0.0
Requires-Dist: ipykernel>=6.0.0
Requires-Dist: ipywidgets>=7.0.0
Requires-Dist: notebook>=6.0.0
Requires-Dist: wfdb~=4.1.2
Provides-Extra: tensorflow
Requires-Dist: tensorflow<=2.12.1,>=2.8.0; platform_system == "Linux" and extra == "tensorflow"
Requires-Dist: tensorflow<=2.12.1,>=2.8.0; platform_system == "Windows" and extra == "tensorflow"
Requires-Dist: tensorflow-macos<=2.12.0,>=2.8.0; platform_system == "Darwin" and extra == "tensorflow"
Provides-Extra: pytorch
Requires-Dist: torch>=1.10.0; extra == "pytorch"
Requires-Dist: zennit==0.5.1; extra == "pytorch"
Provides-Extra: all
Requires-Dist: tensorflow<=2.12.1,>=2.8.0; platform_system == "Linux" and extra == "all"
Requires-Dist: tensorflow<=2.12.1,>=2.8.0; platform_system == "Windows" and extra == "all"
Requires-Dist: tensorflow-macos<=2.12.0,>=2.8.0; platform_system == "Darwin" and extra == "all"
Requires-Dist: torch>=1.10.0; extra == "all"
Requires-Dist: zennit==0.5.1; extra == "all"
Provides-Extra: dev
Requires-Dist: tensorflow<=2.12.1,>=2.8.0; platform_system == "Linux" and extra == "dev"
Requires-Dist: tensorflow<=2.12.1,>=2.8.0; platform_system == "Windows" and extra == "dev"
Requires-Dist: tensorflow-macos<=2.12.0,>=2.8.0; platform_system == "Darwin" and extra == "dev"
Requires-Dist: torch>=1.10.0; extra == "dev"
Requires-Dist: zennit==0.5.1; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=3.4.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: sphinx>=5.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "dev"
Requires-Dist: pydata-sphinx-theme>=0.13; extra == "dev"
Requires-Dist: nbsphinx>=0.9; extra == "dev"
Requires-Dist: myst-parser>=1.0; extra == "dev"
Dynamic: license-file

# SignXAI2

## Project Description

**SIGNed explanations: Unveiling relevant features by reducing bias**

This repository and python package is an extended version of the published python package of the following journal article: https://doi.org/10.1016/j.inffus.2023.101883

If you use the code from this repository in your work, please cite:

```bibtex
@article{Gumpfer2023SIGN,
    title = {SIGNed explanations: Unveiling relevant features by reducing bias},
    author = {Nils Gumpfer and Joshua Prim and Till Keller and Bernhard Seeger and Michael Guckert and Jennifer Hannig},
    journal = {Information Fusion},
    pages = {101883},
    year = {2023},
    issn = {1566-2535},
    doi = {https://doi.org/10.1016/j.inffus.2023.101883},
    url = {https://www.sciencedirect.com/science/article/pii/S1566253523001999}
}
```

![SIGN Explanation](https://pypi-camo.freetls.fastly.net/00b567188fb6bd7ccefc60fbdb099c52905a6941/68747470733a2f2f6172732e656c732d63646e2e636f6d2f636f6e74656e742f696d6167652f312d73322e302d53313536363235333532333030313939392d6761315f6c72672e6a7067)

## Documentation

The documentation for SignXAI2 is available at: https://TimeXAIgroup.github.io/signxai2/index.html

## Requirements

- Python 3.9 or 3.10 (Python 3.11+ is not supported)
- TensorFlow >=2.8.0,<=2.12.1
- PyTorch >=1.10.0
- NumPy, Matplotlib, SciPy

## 🚀 Installation

SignXAI2 requires you to explicitly choose which deep learning framework(s) to install. This ensures you only install what you need.

### Install from PyPI

For TensorFlow users:
```bash
pip install signxai2[tensorflow]
```

For PyTorch users:
```bash
pip install signxai2[pytorch]
```

For both frameworks:
```bash
pip install signxai2[all]
```

For development (includes all frameworks + dev tools):
```bash
pip install signxai2[dev]
```

**Note:** Installing `pip install signxai2` alone is not supported. You must specify at least one framework.

### Install from source

```bash
git clone https://github.com/TimeXAIgroup/signxai2.git
cd signxai2

# Choose your installation:
pip install -e .[tensorflow]    # TensorFlow only
pip install -e .[pytorch]       # PyTorch only  
pip install -e .[all]           # Both frameworks
pip install -e .[dev]           # Development (all frameworks + tools)
```

## Setup of Git LFS

Before you get started please set up Git LFS to download the large files in this repository. This is required to access the pre-trained models and example data.

```bash
git lfs install
```

## 📦 Load Data and Documentation

After installation, run the setup script to download documentation, examples, and sample data:

```bash
bash ./prepare.sh
```

This will download:
- 📚 Full documentation (viewable at docs/index.html)
- 📝 Example scripts and notebooks (examples/)
- 📊 Sample ECG data and images (examples/data/)

## Examples

To get started with SignXAI2 Methods, please follow the example tutorials ('examples/tutorials/').

## Features

- Support for TensorFlow and PyTorch models
- Consistent API across frameworks with dynamic method parsing
- Wide range of explanation methods:
  - Gradient-based: Vanilla gradient, Integrated gradients, SmoothGrad
  - Class activation maps: Grad-CAM
  - Guided backpropagation
  - Layer-wise Relevance Propagation (LRP)
  - Sign-based thresholding for binary relevance maps
- No wrapper classes - direct method calls with parameters embedded in method names

## Development version

To install with development dependencies for testing and documentation:

```bash
pip install signxai2[dev]
```

Or from source:
```bash
git clone https://github.com/TimeXAIgroup/signxai2.git
cd signxai2
pip install -e ".[dev]"
```

## Project Structure

- `signxai/`: Main package with unified API and framework detection
- `signxai/tf_signxai/`: TensorFlow implementation using modified iNNvestigate
- `signxai/torch_signxai/`: PyTorch implementation using zennit with custom hooks
- `examples/tutorials/`: Tutorials for both frameworks covering images and time series
- `examples/comparison/`: Implementation for reproducing results from the paper
- `utils/`: Helper scripts for model conversion (tf -> torch) and data preprocessing

## Usage

Please follow the example tutorials in the `examples/tutorials/` directory to get started with SignXAI2 methods. The new API uses dynamic method parsing where parameters are embedded directly in method names:

```python
from signxai import explain

# Basic gradient
explanation = explain(model, x, method_name="gradient")

# Complex method with parameter chaining
explanation = explain(model, x, method_name="gradient_x_input_x_sign_mu_neg_0_5")
```

## License

BSD 3-Clause License - See LICENSE file for details.
