fuzzic 0.5.1
FuzzIC is a Python library for evaluating the interpretability of fuzzy rule bases.
Requires Python: >=3.10
Keywords: fuzzy inference systems, interpretable ai, interpretability measure, explainable ai

# FuzzIC

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

This work was carried out as part of the IFP-in-RL project funded by ANR-22-ASTR-0032 in collaboration with Thales and Sorbonne University.

**FuzzIC** is a Python library for evaluating the **interpretability of fuzzy rule bases**.  
It acts as a command-line tool that automatically analyzes your fuzzy systems and generates an interactive HTML Dashboard.

It computes up to **20 different interpretability criteria**, aggregates them into a global interpretability score, and provides configurable, flexible, and customizable evaluation tools.

![Screen of Dashboard](assets/dashboard_screenshot.png)
---

## 📑 Table of Contents
- [Features](#-features)
- [Installation](#-installation)
- [CLI Usage (Quickstart)](#-quickstart)
- [The Dashboard](#-dashboard)
- [Configuration & Customization](#-configuration)
- [Acknowledgement](#-acknowledgement)
- [License](#-license)

---

## ✨ Features
* **One-Line Evaluation:** Run the full analysis via a simple Command Line Interface (CLI).
* **Interactive Dashboard:** Generates a standalone HTML report visualizing rules, variables, and scores.
* **Global Interpretability Score:** Aggregates individual metrics into a single, comparable score.
* **Extensive Metrics:** Computes up to 19 criteria from the literature.
* **Flexible Inputs:** Supports **XML** and **FisPro (.fis)** rule base formats.
* **Customizable:** Easily add new criteria or tweak configuration.

---

## 🛠 Installation
You can use pip:

```bash
pip install fuzzic
```

or clone and install locally:

```bash
git clone https://gitlab.lip6.fr/pontoizeau/fuzzic.git
cd fuzzic
pip install -e .
```

> ✅ Requirements: Python ≥ 3.8, `numpy`, `matplotlib`, etc.  
(Dependencies are installed automatically via `pip`.)

---

## 🚀 Quickstart

The easiest way to use FuzzIC is through the command line.

### Analyze a single file

To evaluate a specific rule base file (.xml or .fis):

```bash
fuzzic my_rulebase.xml
```

### Analyze a project folder

To evaluate a folder containing multiple rule bases (ideal for comparing models):

```bash
fuzzic ./my_fuzzy_project/
```
### What happens next? 
FuzzIC will process the inputs and automatically generate a dashboard folder containing an dashboard.html file. 
Open this file in your browser to view the results.

---

## 📊 The HTML Dashboard

The generated dashboard allows you to explore:
- Visualizations: Interactive plots of Linguistic Variables (Fuzzy Sets) and Rules.
- Detailed Metrics: Tables showing all criteria score. 
- Global Interpretability Score: Aggregate your criteria to evaluate the overall interpretability.
- Enhance your rule bases: Use the mouse to reveal what reduces interpretability.
- Comparison: Side-by-side comparison if multiple rule bases were analyzed.

---

## 🔧 Configuration & Customization

### Input
- Rule bases in **XML** (.xml) or **FisPro** (.fis) format (templates provided).
- Fuzzy sets must be **trapezoidal** or **Gaussian**.
- Specific dataset for interpretability analysis (optional) in CSV:
  - First line = labels
  - Following lines = instances (comma-separated)

### Output
- A **JSON file** is provided containing all computed criteria values for the rule bases.


### Configuration
All configuration parameters are managed in:

```python
from fuzzic.configuration.config import config
config.sample_size = 800 # Modifying the size of sampling
print(config.reminder())
```


### Main parameters
- **Criteria configuration**  
  similarity measure, t-norm, t-conorm...
- **Aggregators**  
  aggregators functions for criteria, global score...
- **Sampling**  
  sampling size, admitted error, space discretization size...
- **User-defined**  
  Add your own parameters with:
  ```python
  config.add_param('my_param', [1, 2, 3], 'Example custom parameter')
  ```


---

## 🐍 Python Library Usage

For advanced users who want to integrate FuzzIC into their Python pipelines or customize the evaluation process manually.

### Add a new criterion
Define a function taking a **rulebase** object and returning a `dict`:

```python
def interpretability(rulebase):
    return {"warning": "Nothing to say", "score": 1.0}
```

Register it in the global `CRITERIA` list:

```python
from fuzzic.interpretability.criteria import CRITERIA, criterion

CRITERIA.append(criterion(
    name="example",
    category="linguistic variables",
    direction="max",
    active=True,
    func_interpretability=interpretability
))
```

Set the criterion parameter:
- criterion_name: The name of your criterion
- category: The object which the criterion applies on. Current are ['linguistic variables', 'fuzzy rule', 'fuzzy set', 'fuzzy rule base', 'fuzzy sets'].
- direction : if the criterion must be maximized, minimized
- active: if you wish to evaluate this criterion or not during evaluation
- func_interpretability: the reference to the interpretability evaluation function of this criterion

Manage active criteria:
```python
import fuzzic.interpretability.criteria as ic

ic.activate("normality")
ic.deactivate("coverage")
print(ic.status())
```

Here is a full example:
```python
from fuzzic.study.study import Study, create_project
from fuzzic.interpretability.interpretability_manager import  status, deactivate
from fuzzic.configuration.config import config

#### IF A NEW INTERPRETABILITY CRITERION HAS TO BE DEFINED IN ADDITION
from fuzzic.interpretability.interpretability_manager import CRITERIA, criterion

def interpretability(rulebase):
    ...
    return {"warning" : 'Nothing to say', "score" : 1.}

CRITERIA.append(criterion(name="example", category="linguistic variables", direction="max",
          active=True, func_interpretability=interpretability))
#########

config.add_param('additional_param', [1, 2, 3, 4], 'A example of user criteria')
print(config.reminder())
config.additional_param = [3, 2]

study_name = "climatiseur" # the folder name in working_dir/study where the rule-base and all the results are/will be stored

create_project(study_name)

deactivate("coverage")
print(status())

S = Study(study_name)
S.evaluate()
S.generate_dashboard()
```

---

## 🙏 Acknowledgement

This work has been funded by the project **IFP-in-RL, ANR-22-ASTR-0032**.

---

## 📜 License

Distributed under the [MIT License](https://choosealicense.com/licenses/mit/).