Ex-Fuzzy

🚀 A modern, explainable fuzzy logic library for Python

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

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 supports fine-tuning of different hyperparameters, like tournament size, crossover rate, etc.
• 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.

from ex_fuzzy import BaseFuzzyRulesRegressor
from sklearn.datasets import make_regression
from sklearn.model_selection import train_test_split

X, y = make_regression(n_samples=500, n_features=5, noise=5.0, random_state=0)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.25, random_state=0
)

regressor = BaseFuzzyRulesRegressor(
    nRules=20,
    nAnts=3,
    consequent_type="crisp",  # use "fuzzy" for Mamdani consequents
    backend="pymoo",
)
regressor.fit(X_train, y_train, n_gen=50, pop_size=50)

predictions = regressor.predict(X_test)
print(f"Test R2: {regressor.score(X_test, y_test):.3f}")
regressor.print_rules()

📊 Visualizations

Ex-Fuzzy provides beautiful visualizations to understand your fuzzy models:

📈 Statistical Analysis

Monitor pattern stability and variable usage across multiple runs:

🎯 Bootstrap Confidence Intervals

Obtain statistical confidence intervals for your metrics:

⚡ Performance

Accuracy and model size on 67 KEEL datasets

Ex-Fuzzy 2.0 vs Ex-Fuzzy 3.0 training speed

Our implementation is getting more efficient! This experiment crosses 1,000 / 10,000 / 100,000 samples with 10 / 50 / 200 features, for both fixed and optimized partitions. All of them using CPU backend.

EvoX GPU acceleration

A three-seed benchmark compared identical EvoX CPU and CUDA searches on 100,000 samples and 200 features (Type-1, 20 rules, 4 antecedents, population 40 and 5 generations):

Backend Comparison

Ex-Fuzzy supports two evolutionary optimization backends:

When to Use Each Backend

Use PyMoo when:

• Working with small to medium datasets
• Running on CPU-only environments
• Need checkpoint/resume functionality
• Memory is limited

Use EvoX when:

• Have GPU available (CUDA recommended)
• Working with large datasets (>10,000 samples)
• No checkpointing (Evox does not support checkpointing yet)

Both backends automatically batch operations to fit available memory and large datasets are processed in chunks to prevent out-of-memory errors.

🛠️ Examples

🔬 Notebooks

Seven executed notebooks in Demos/ walk through the library; they render on GitHub with their outputs.

Real Applications

• Ex-Fuzzy in fNIRS data: https://github.com/jjcato9/ex_fuzzy_fnirs_demo

💻 Code Examples

# Plot fuzzy variable partitions
classifier.plot_fuzzy_variables()

from ex_fuzzy import BaseFuzzyRulesClassifier, BaseFuzzyRulesRegressor

# Create classifier with EvoX backend for GPU acceleration
classifier = BaseFuzzyRulesClassifier(
    nRules=30,
    nAnts=4,
    backend='evox',  # Use GPU-accelerated EvoX backend
    verbose=True
)

# Train with GPU acceleration
classifier.fit(X_train, y_train, 
              n_gen=50,
              pop_size=100)

# Early stopping is enabled by default:
# patience=10, min_delta=1e-4

# Regression uses the same EvoX backend. Both crisp and fuzzy
# consequents are evaluated in memory-aware PyTorch batches.
regressor = BaseFuzzyRulesRegressor(
    nRules=30,
    nAnts=4,
    consequent_type="crisp",
    backend="evox",
)
regressor.fit(X_reg_train, y_reg_train, n_gen=50, pop_size=100)

# CUDA is selected automatically when available; otherwise EvoX uses CPU.
print(regressor.optimization_device_)  # "cuda" or "cpu"
print(regressor.gpu_accelerated_)      # True only when CUDA was used

from ex_fuzzy.bootstrapping_test import generate_bootstrap_samples

# Generate bootstrap samples
bootstrap_samples = generate_bootstrap_samples(X_train, y_train, n_samples=100)

# Evaluate model stability
bootstrap_results = []
for X_boot, y_boot in bootstrap_samples:
    classifier_boot = BaseFuzzyRulesClassifier(nRules=10)
    classifier_boot.fit(X_boot, y_boot)
    accuracy = classifier_boot.score(X_test, y_test)
    bootstrap_results.append(accuracy)

print(f"Bootstrap confidence interval: {np.percentile(bootstrap_results, [2.5, 97.5])}")

📚 Documentation

• 📖 User Guide: Comprehensive tutorials and examples
• 🔧 API Reference: Detailed function and class documentation
• 🚀 Quick Start Guide: Get up and running fast
• 📊 Examples Gallery: Real-world use cases

🛡️ Requirements

Core Dependencies

• Python >= 3.10
• NumPy
• Pandas
• Matplotlib
• Scikit-learn
• PyMOO >= 0.6.2

Optional Dependencies

• EvoX >= 1.3.0 (for GPU-accelerated evolutionary optimization): pip install "ex-fuzzy[evox]"
• PyTorch >= 2.6.0 (required by EvoX)

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Bug Reports

Found a bug? Please open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• System information

Feature Requests

Have an idea? Submit a feature request with:

• Clear use case description
• Proposed API design
• Implementation considerations

💻 Code Contributions

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes with tests
4. Run the test suite: pytest tests/ -v
5. Submit a pull request

🧪 Running Tests

# Install test dependencies
pip install pytest pytest-cov

# Run all tests
pytest tests/ -v

# Run tests with coverage report
pytest tests/ --cov=ex_fuzzy --cov-report=html

# Run specific test file
pytest tests/test_fuzzy_sets_comprehensive.py -v

📄 License

This project is licensed under the AGPL v3 License - see the LICENSE file for details.

📑 Citation

If you use Ex-Fuzzy in your research, please cite our paper:

@article{fumanalex2024,
  title = {Ex-Fuzzy: A library for symbolic explainable AI through fuzzy logic programming},
  journal = {Neurocomputing},
  pages = {128048},
  year = {2024},
  issn = {0925-2312},
  doi = {10.1016/j.neucom.2024.128048},
  url = {https://www.sciencedirect.com/science/article/pii/S0925231224008191},
  author = {Javier Fumanal-Idocin and Javier Andreu-Perez}
}

👥 Main Authors

• Javier Fumanal-Idocin - Lead Developer
• Javier Andreu-Perez - Development manager & Licensing officer

🌟 Acknowledgments

• Special thanks to all contributors
• This research has been supported by EU Horizon Europe under the Marie Skłodowska-Curie COFUND grant No 101081327 YUFE4Postdocs.

⭐ Star us on GitHub if you find Ex-Fuzzy useful!