🎯 Overview
Ex-Fuzzy is a comprehensive Python library for explainable artificial intelligence through fuzzy logic programming. Built with a focus on accessibility and visualization, it enables researchers and practitioners to create interpretable machine learning models using fuzzy association rules.
New: Try Ex-Fuzzy labs! Our new plug and play web interface where you can quickly test how Ex-Fuzzy would work in your data: ExFuzzy Labs
See it on real data: ExFuzzy Atlas shows Ex-Fuzzy models on public air quality, river water and taxi demand data: read each rule and see where on the map it decides (source).
Why Ex-Fuzzy?
- 🔍 Explainable AI: Create interpretable models that humans can understand. Support for classification and regression problems.
- 📊 Rich Visualizations: Beautiful plots and graphs for fuzzy sets and rules.
- 🛠️ Scikit-learn Compatible: Familiar API for machine learning practitioners.
- 🚀 High Performance: Optimized algorithms with optional GPU support using Evox (https://github.com/EMI-Group/evox).
✨ Features
Explainable Rule-Based Learning
- Fuzzy Association Rules: For both classification and regression problems with genetic fine-tuning.
- FERL Rule Trees: Greedy fuzzy rule learning with native belief,
plausibility, ignorance, and set-valued predictions.
- Out-of-the-box Results: Complete compatibility with scikit-learn, minimal to none fuzzy knowledge required to obtain good results.
- Complete Complexity Control: Number of rules, rule length, linguistic variables, etc. can be specified by the user with strong and soft constrains.
- Statistical Analysis of Results: Confidence intervals for all rule quality metrics, repeated experiments for rule robustness.
- Conformal Predictions Supported Out-of-the-box: Use Rule classifiers with conformal guarantees to obtain more reliable classification/regression.
Complete Rule Base Visualization and Validation
- Comprehensive Plots: Visualize fuzzy sets and rules.
- Robustness Metrics: Compute validation of rules, ensure linguistic meaning of fuzzy partitions, robustness metrics for rules and space partitions, reproducible experiments, etc.
Advanced Learning Routines
- Multiple Backend Support: Choose between PyMoo (CPU) and EvoX (GPU-accelerated) backends for evolutionary optimization.
- Genetic Algorithms: Rule base optimization maximizes macro F1 with small penalties for classes without rules and for model size, or searches the accuracy–size trade-off with NSGA-II (
algorithm='nsga2') and keeps the Pareto front to choose from. Hyperparameters like tournament size and crossover rate can be tuned.
- GPU Genetic Acceleration: EvoX backend with PyTorch provides significant speedups for large datasets and complex rule bases.
- Extensible Architecture: Easy to extend with custom components.
Complete Fuzzy Logic Systems Support
- Multiple Fuzzy Set Types: Classic, Interval-Valued Type-2, and General Type-2 fuzzy sets
- Linguistic Variables: Automatic generation with quantile-based optimization.
🚀 Quick Start
Installation
Install Ex-Fuzzy using pip:
# Basic installation (CPU only, PyMoo backend)
pip install ex-fuzzy
# With GPU support (EvoX backend with PyTorch)
pip install "ex-fuzzy[evox]"
Basic Usage
from ex_fuzzy import BaseFuzzyRulesClassifier
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
# Load data
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3, random_state=42)
# Create and train fuzzy classifier
classifier = BaseFuzzyRulesClassifier(
nRules=15,
nAnts=4,
backend="pymoo" # or "evox" for GPU acceleration
)
# Train the model
classifier.fit(X_train, y_train)
# Make predictions
predictions = classifier.predict(X_test)
# Evaluate and visualize fuzzy partitions
from ex_fuzzy.eval_tools import eval_fuzzy_model
eval_fuzzy_model(classifier, X_train, y_train, X_test, y_test,
plot_partitions=True)
FERL Evidential Classification
FERL learns a fuzzy rule tree and derives Dempster--Shafer evidence directly
from rule firing strengths. It is implemented natively in Ex-Fuzzy and needs no
separate fuzzy-tree package.
from ex_fuzzy import FERL
ferl = FERL(max_rules=15, random_state=0)
ferl.fit(X_train, y_train)
predictions = ferl.predict(X_test)
betp, belief, plausibility, ignorance = ferl.predict_credal(X_test)
prediction_sets = ferl.predict_set(X_test)
ferl.print_tree()
Use split_mode="learned" for data-driven soft split locations or
partition="mdlp" for supervised trapezoidal partitions. Native FERL sets are
calibration-free evidential outputs; use ConformalFuzzyClassifier when a
finite-sample marginal coverage guarantee is required.
For higher accuracy with the same evidential outputs, DeepFERL grows a deep
tree of learned, Gini-placed soft splits and votes over its leaves.
Regression Usage
BaseFuzzyRulesRegressor learns interpretable Type-1 rules for continuous
targets. It supports crisp Takagi-Sugeno consequents and fuzzy Mamdani
consequents.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
