ex-fuzzy 2.1.5

Library to perform explainable AI using fuzzy logic.

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

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 torch

Basic Usage

import numpy as np
from ex_fuzzy.evolutionary_fit 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(
    n_rules=15,
    n_antecedents=4,
    fuzzy_type="t1",  # Type-1 fuzzy sets
    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
from ex_fuzzy.eval_tools import eval_fuzzy_model
eval_fuzzy_model(classifier, X_train, y_train, X_test, y_test, 
                plot_rules=True, plot_partitions=True)

📊 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

Backend Comparison

Ex-Fuzzy supports two evolutionary optimization backends:

Backend	Hardware	Best For
PyMoo	CPU	Small datasets (<10K samples), checkpoint support
EvoX	GPU	Large datasets with high generation counts

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.

Conformal Learning Support

Ex-Fuzzy supports conformal learning for more reliable predictions.

What is supported:

• Split conformal calibration on held-out calibration data

• Set-valued predictions with target coverage 1 - alpha

• Rule-aware conformal analysis: not only classes, but rule firings are also analyzed according to the nonconformity scores.

• Coverage and efficiency metrics.

• Demos:

  • Notebook: Demos/conformal_learning_demo.ipynb
  • Script: Demos/demos_module/conformal_learning_demo.py

🛠️ Examples

🔬 Interactive Jupyter Notebooks

Try our hands-on examples in Google Colab:

Topic	Description	Colab Link
Basic Classification	Introduction to fuzzy classification
Custom Loss Functions	Advanced optimization techniques
Rule File Loading	Working with text-based rule files
Advanced Rules	Using pre-computed rule populations
Temporal Fuzzy Sets	Time-aware fuzzy reasoning
Rule Mining	Automatic rule discovery
EvoX Backend	GPU-accelerated training with EvoX	📓 Notebook
Conformal Learning	Set-valued predictions with calibrated coverage	📓 Notebook

💻 Code Examples

🔍 Advanced Rule Mining

from ex_fuzzy.rule_mining import mine_rulebase
from ex_fuzzy.utils import create_fuzzy_variables

# Create fuzzy variables
variables = create_fuzzy_variables(X_train, ['low', 'medium', 'high'])

# Mine rules from data
rules = mine_rulebase(X_train, variables, 
                     support_threshold=0.1, 
                     max_depth=3)

print(f"Discovered {len(rules)} rules")

📊 Custom Visualization

from ex_fuzzy.vis_rules import visualize_rulebase

# Create custom rule visualization
visualize_rulebase(classifier.rule_base, 
                  export_path="my_rules.png",
                  layout="spring")

# Plot fuzzy variable partitions
classifier.plot_fuzzy_variables()

🚀 GPU-Accelerated Training (EvoX Backend)

from ex_fuzzy import BaseFuzzyRulesClassifier

# Create classifier with EvoX backend for GPU acceleration
classifier = BaseFuzzyRulesClassifier(
    n_rules=30,
    n_antecedents=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)

# EvoX provides significant speedups for:
# - Large datasets (>10,000 samples)
# - Complex rule bases (many rules/antecedents)
# - High generation counts
print("Training completed with GPU acceleration!")

🧪 Bootstrap Analysis

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(n_rules=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.7
• NumPy >= 1.19.0
• Pandas >= 1.2.0
• Matplotlib >= 3.3.0
• PyMOO >= 0.6.0

Optional Dependencies

• NetworkX >= 2.6 (for rule visualization)
• EvoX >= 0.8.0 (for GPU-accelerated evolutionary optimization)
• PyTorch >= 1.9.0 (required by EvoX for GPU acceleration)
• Scikit-learn >= 0.24.0 (for compatibility examples)

🤝 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

📖 Documentation

Help improve documentation by:

• Adding examples
• Fixing typos
• Improving clarity
• Adding translations

📄 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 - 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!