fmae 0.1.0

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.

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 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:

pip install fmae

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

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

Semantic Inference Explanation

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:

@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.