Metadata-Version: 2.4
Name: fmae
Version: 0.1.0
Summary: This project provides the official Python library of FMAE (Fuzzy Model-Agnostic Explanation), which is a post-hoc XAI method designed to explain the decision-making behavior of pre-trained black-box predictive models.
Author-email: Faliang Yin <faliang.yin@gmail.com>, Hak-Keung Lam <hak-keung.lam@kcl.ac.uk>, David Watson <david.watson@kcl.ac.uk>
License: MIT License
        
        Copyright (c) 2025 Faliang Yin, Hak-Keung Lam, David Watson
        
        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.
        
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Dynamic: license-file

# FMAE (Fuzzy Model-Agnostic Explanation) Python Library

This project provides the **official Python library of FMAE (Fuzzy Model-Agnostic Explanation)**. Please visit our [FMAE Repository on GitHub](https://github.com/FaliangYin/FMAE-library) for more details.

FMAE is a post-hoc explainable artificial intelligence (XAI) method designed to explain the decision-making behavior of **pre-trained black-box predictive models**.

The algorithms implemented in this library are based on the following paper:

> **Hierarchical Fuzzy Model-Agnostic Explanation: Framework, Algorithms and Interface for XAI**  
> Faliang Yin, Hak-Keung Lam, David Watson  
> *IEEE Transactions on Fuzzy Systems*  
> https://ieeexplore.ieee.org/document/10731553

---
## Installation

You can install the FMAE library directly via `pip`:

```bash
pip install fmae
```

Alternatively, you can clone this repository and install it manually:

```bash
pip install .
```

---

## Usage Examples

A simple usage example for generating **local explanations** is provided in:

```
examples/case_WBC.ipynb
```

This notebook demonstrates how to apply FMAE to a pre-trained black-box classifier to explain its decision on a specific instance of interest.
### Feature Salience Explanation
![class0](doc/WBC_Class0.png)
![class1](doc/WBC_Class1.png)

### Semantic Inference Explanation
```aiignore
r1: IF Bare Nuclei is medium, Normal Nucleoli is medium, THEN predicted as Benign with 0.972, Malignant with 0.023;
r2: IF Bare Nuclei is medium, Normal Nucleoli is low, THEN predicted as Benign with 1.003, Malignant with 0.004;
r3: IF Bare Nuclei is high, Normal Nucleoli is medium, THEN predicted as Benign with 0.839, Malignant with 0.170;
r4: IF Bare Nuclei is medium, Uniformity of Cell Size is low, Normal Nucleoli is medium, THEN predicted as Benign with 0.986, Malignant with 0.010;
r5: IF Bare Nuclei is medium, Uniformity of Cell Size is high, Normal Nucleoli is medium, THEN predicted as Benign with 0.866, Malignant with 0.130;
r6: IF Bare Nuclei is medium, Clump Thickness is high, Normal Nucleoli is medium, THEN predicted as Benign with 0.879, Malignant with 0.112;
r7: IF Bare Nuclei is medium, Normal Nucleoli is medium, Bland Chromatin is low, THEN predicted as Benign with 0.967, Malignant with 0.010;
r8: IF Bare Nuclei is medium, Normal Nucleoli is high, THEN predicted as Benign with 0.959, Malignant with 0.064;
r9: IF Bare Nuclei is medium, Normal Nucleoli is medium, Bland Chromatin is high, THEN predicted as Benign with 0.835, Malignant with 0.137;
r10: IF Bare Nuclei is medium, Clump Thickness is low, Normal Nucleoli is medium, THEN predicted as Benign with 0.960, Malignant with 0.011;
r11: IF Bare Nuclei is low, Normal Nucleoli is medium, THEN predicted as Benign with 1.028, Malignant with 0.008;
```

For more detailed guidance and comprehensive experimental cases, including hierarchical explanations and extended evaluations, please refer to:

- Our original paper (Open Access):  
  https://kclpure.kcl.ac.uk/portal/en/publications/hierarchical-fuzzy-model-agnostic-explanation-framework-algorithm/
- Our code repository for paper reproduction:  
  https://github.com/FaliangYin/fmae

---

## Classes and Functions

The FMAE library provides the following classes and main functions:

| Name                  | Description                                                                                                                                                                                |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| FmaeBasicFls          | Explainer for tabular explanation task with SINGLE instance, corresponding to 'Initial FLS' in Fig.2 in paper where rule reduction and premise condensation are not enabled                |
| FmaeBasicExplainer    | Explainer for tabular explanation task with SINGLE instance, corresponding to 'Initial explainer' in Fig.2 in paper where rule reduction and premise condensation can be enabled           |
| FmaeFls               | Explainer for tabular explanation task with MULTIPLE instances, corresponding to 'FMAE:Initial FLS' in TABLE I in paper where rule reduction and premise condensation are not enabled      |
| FmaeExplainer         | Explainer for tabular explanation task with MULTIPLE instances, corresponding to 'FMAE:Initial explainer' in TABLE I in paper where rule reduction and premise condensation can be enabled |
| FmaeDownscaling       | Explainer for downscaling the explanation, corresponding to the experiment of Section V.C Case 2 Downscaling via simplification of the paper                                               |
| FmaeUpscaling         | Explainer for upscaling the explanation, corresponding to the experiment of Section V.D Case 3 Upscaling via aggregation of the paper                                                      |
| print_rules           | Deliver the semantic inference explanations by the IF-THEN rules revealing the decision logic of the black-box model                                                                       |
| plot_feature_salience | Deliver the feature salience explanations by the salience values illustrating the contribution of each feature                                                                             |

Please refer to the docstrings in the code for more details on each class and function.

---

## Citation

If you use this library in your research, please cite the following paper:

```bibtex
@ARTICLE{fmae, 
  author={Yin, Faliang and Lam, Hak-Keung and Watson, David}, 
  journal={IEEE Transactions on Fuzzy Systems}, 
  title={Hierarchical Fuzzy Model-Agnostic Explanation: Framework, Algorithms, and Interface for XAI}, 
  year={2025}, 
  volume={33}, 
  number={2}, 
  pages={549-558},
  doi={10.1109/TFUZZ.2024.3485212}}
```

---

## License

This project is released under the MIT License. See the `LICENSE` file for details.
