fuzzic 0.5.1

FuzzIC is a Python library for evaluating the interpretability of fuzzy rule bases.

FuzzIC

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.

📑 Table of Contents

• Features
• Installation
• CLI Usage (Quickstart)
• The Dashboard
• Configuration & Customization
• Acknowledgement
• 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:

pip install fuzzic

or clone and install locally:

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

fuzzic my_rulebase.xml

Analyze a project folder

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

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:

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:

  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:

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

Register it in the global CRITERIA list:

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:

import fuzzic.interpretability.criteria as ic

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

Here is a full example:

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.