🚀 A modern, explainable fuzzy logic library for Python
Features • Quick Start • Examples • Documentation • Contributing • Citation
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.
- 🔍 Explainable AI: Create interpretable models that humans can understand
- 📊 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
- 📚 Comprehensive: Support for classification, regression, and rule mining
- 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, .
- Comprehensive Plots: Visualize fuzzy sets and rules.
- Network Graphs: Rule visualizations using NetworkX.
- Robustness Metrics: Compute validation of rules, ensure linguistic meaning of fuzzy partitions, robustness metrics for rules and space partitions, reproducible experiments, etc.
- Genetic Algorithms: Rule base optimization using PyMOO supports fine-tuning of different hyperparameters, like tournament size, crossover rate, etc.
- Pre-mining and Rule Search: start with good initial or prior populations, and then refine those results to obtain a good classifier using genetic optimization.
- Extensible Architecture: Easy to extend with custom components.
- Multiple Fuzzy Set Types: Classic, Interval-Valued Type-2, and General Type-2 fuzzy sets
- Linguistic Variables: Automatic generation with quantile-based optimization.
- Linguistic Hedges: Natural language modifiers for enhanced expressiveness.
- Temporal Fuzzy Sets: Time-aware fuzzy reasoning
Install Ex-Fuzzy using pip:
pip install ex-fuzzyimport numpy as np
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(
n_rules=15,
n_antecedents=4,
fuzzy_type="t1" # Type-1 fuzzy sets
)
# 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)Ex-Fuzzy provides beautiful visualizations to understand your fuzzy models:
Monitor pattern stability and variable usage across multiple runs:
Obtain statistical confidence intervals for your metrics:
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 | |
🔍 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()🧪 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])}")- 📖 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
- Python >= 3.7
- NumPy >= 1.19.0
- Pandas >= 1.2.0
- Matplotlib >= 3.3.0
- PyMOO >= 0.6.0
- NetworkX >= 2.6 (for rule visualization)
- PyTorch >= 1.9.0 (for GPU acceleration)
- Scikit-learn >= 0.24.0 (for compatibility examples)
We welcome contributions from the community! Here's how you can help:
Found a bug? Please open an issue with:
- Clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- System information
Have an idea? Submit a feature request with:
- Clear use case description
- Proposed API design
- Implementation considerations
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make your changes with tests
- Submit a pull request
Help improve documentation by:
- Adding examples
- Fixing typos
- Improving clarity
- Adding translations
This project is licensed under the AGPL v3 License - see the LICENSE file for details.
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}
}- Javier Fumanal-Idocin - Lead Developer
- Javier Andreu-Perez - Co-lead and licensing officer
- Special thanks to all contributors
- This research has been supported by the European Union and the University of Essex under a Marie Sklodowska-Curie YUFE4 postdoc action.
⭐ Star us on GitHub if you find Ex-Fuzzy useful!
