# IEMM - Iterative Evidential Mistakeness Minimization
IEMM is a Python library for **explainable evidential clustering** that provides interpretable decision tree explanations for clustering results in the presence of uncertain and imprecise data.
Real-world data often contains imperfections characterized by uncertainty and imprecision, which traditional clustering methods struggle to handle effectively. Evidential clustering, based on Dempster-Shafer theory, addresses these challenges but lacks explainability—a crucial requirement for high-stakes domains such as healthcare.
This library implements the **Iterative Evidential Mistake Minimization (IEMM)** algorithm, which generates interpretable and cautious decision tree explanations for evidential clustering functions. The algorithm accounts for decision-maker preferences and can provide satisfactory cautious explanations.
**For more details, see the original paper: [Explainable Evidential Clustering](https://arxiv.org/abs/2507.12192).**
## Citation
If you use this library in your research, please cite:
```bibtex
@article{souzaExplainableEvidentialClustering2025,
title = {Explainable Evidential Clustering},
author = {Lopes de Souza, Victor F. and Bakhti, Karima and Ramdani, Sofiane and Mottet, Denis and Imoussaten, Abdelhak},
publisher = {arXiv},
doi = {10.48550/arXiv.2507.12192},
}
```
## Installation
### From source (development)
```bash
git clone https://github.com/victorsouza89/iemm.git
cd iemm
pip install -e .
```
## Quick Start
If you're new to IEMM, we strongly recommend starting with `very_simple_example.ipynb`. It provides:
- Clear explanations of each step
- Visual outputs to understand the algorithm
- Simple synthetic data for easy comprehension
- Complete workflow from data loading to result interpretation
```bash
cd experiments
jupyter notebook very_simple_example.ipynb
```
For a quick example of how to use the IEMM library, you can also run the following code snippet:
```python
from iemm import IEMM
import numpy as np
# Create an IEMM classifier
classifier = IEMM(lambda_mistakeness=1.0)
# Fit the model with your data
# X: feature matrix
# mass: mass functions for each sample
# F: focal sets matrix
classifier.fit(X, mass, F)
# Make predictions
predictions = classifier.predict(X_test)
```
## Examples and Experiments
The `experiments/` folder contains several Jupyter notebooks demonstrating the IEMM library:
- **`very_simple_example.ipynb`** - **Recommended for new users!** A step-by-step tutorial showing how to use IEMM with a simple 2D synthetic dataset. This notebook is perfect for familiarizing yourself with the library's basic functionality, including data preparation, ECM clustering, IEMM training, visualization, and decision tree interpretation.
The other notebooks were used in the original paper and provide more advanced examples:
- **`iemm_notebook.ipynb`** - Core implementation with advanced visualization functions and evaluation metrics used across different experiments.
- **`main.ipynb`** - Comprehensive experiments running IEMM on multiple datasets including synthetic 2D data and real-world credal datasets.
## Modules
- **`iemm.core`**: Main IEMM algorithm
- **`iemm.belief`**: Belief function operations and transformations
- **`iemm.utils`**: Utility functions for distance calculations and criteria
## Requirements
- Python >= 3.9
- NumPy >= 1.19.0
- pandas >= 1.2.0
- scikit-learn >= 0.24.0
- schemdraw >= 0.11
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Acknowledgments
Some code snippets were adapted from [Conflict EDT](https://github.com/ArthurHoa/conflict-edt/tree/master) (for evidential decision trees construction) and [iBelief](https://github.com/jusdesoja/iBelief_python) (for belief function operations).
Raw data
{
"_id": null,
"home_page": "https://github.com/victorsouza89/iemm",
"name": "iemm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Victor Souza <victorflosouza@gmail.com>",
"keywords": "belief functions, evidential decision trees, machine learning, uncertainty",
"author": "Victor Souza",
"author_email": "Victor Souza <victorflosouza@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a9/e5/23a5d7d7363d9632bfcd60a89fa73fda524ec6d899dd010b78ff1bbeace4/iemm-0.1.0.tar.gz",
"platform": null,
"description": "# IEMM - Iterative Evidential Mistakeness Minimization\n\nIEMM is a Python library for **explainable evidential clustering** that provides interpretable decision tree explanations for clustering results in the presence of uncertain and imprecise data.\n\nReal-world data often contains imperfections characterized by uncertainty and imprecision, which traditional clustering methods struggle to handle effectively. Evidential clustering, based on Dempster-Shafer theory, addresses these challenges but lacks explainability\u2014a crucial requirement for high-stakes domains such as healthcare.\n\nThis library implements the **Iterative Evidential Mistake Minimization (IEMM)** algorithm, which generates interpretable and cautious decision tree explanations for evidential clustering functions. The algorithm accounts for decision-maker preferences and can provide satisfactory cautious explanations.\n\n**For more details, see the original paper: [Explainable Evidential Clustering](https://arxiv.org/abs/2507.12192).**\n\n## Citation\n\nIf you use this library in your research, please cite:\n\n```bibtex\n@article{souzaExplainableEvidentialClustering2025,\n title = {Explainable Evidential Clustering},\n author = {Lopes de Souza, Victor F. and Bakhti, Karima and Ramdani, Sofiane and Mottet, Denis and Imoussaten, Abdelhak},\n publisher = {arXiv},\n doi = {10.48550/arXiv.2507.12192},\n}\n```\n\n## Installation\n\n### From source (development)\n\n```bash\ngit clone https://github.com/victorsouza89/iemm.git\ncd iemm\npip install -e .\n```\n\n## Quick Start\n\nIf you're new to IEMM, we strongly recommend starting with `very_simple_example.ipynb`. It provides:\n- Clear explanations of each step\n- Visual outputs to understand the algorithm\n- Simple synthetic data for easy comprehension\n- Complete workflow from data loading to result interpretation\n\n```bash\ncd experiments\njupyter notebook very_simple_example.ipynb\n```\n\nFor a quick example of how to use the IEMM library, you can also run the following code snippet:\n\n```python\nfrom iemm import IEMM\nimport numpy as np\n\n# Create an IEMM classifier\nclassifier = IEMM(lambda_mistakeness=1.0)\n\n# Fit the model with your data\n# X: feature matrix\n# mass: mass functions for each sample\n# F: focal sets matrix\nclassifier.fit(X, mass, F)\n\n# Make predictions\npredictions = classifier.predict(X_test)\n```\n\n## Examples and Experiments\n\nThe `experiments/` folder contains several Jupyter notebooks demonstrating the IEMM library:\n- **`very_simple_example.ipynb`** - **Recommended for new users!** A step-by-step tutorial showing how to use IEMM with a simple 2D synthetic dataset. This notebook is perfect for familiarizing yourself with the library's basic functionality, including data preparation, ECM clustering, IEMM training, visualization, and decision tree interpretation.\n\nThe other notebooks were used in the original paper and provide more advanced examples:\n- **`iemm_notebook.ipynb`** - Core implementation with advanced visualization functions and evaluation metrics used across different experiments.\n- **`main.ipynb`** - Comprehensive experiments running IEMM on multiple datasets including synthetic 2D data and real-world credal datasets.\n\n## Modules\n\n- **`iemm.core`**: Main IEMM algorithm\n- **`iemm.belief`**: Belief function operations and transformations\n- **`iemm.utils`**: Utility functions for distance calculations and criteria\n\n## Requirements\n\n- Python >= 3.9\n- NumPy >= 1.19.0\n- pandas >= 1.2.0\n- scikit-learn >= 0.24.0\n- schemdraw >= 0.11\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgments\n\nSome code snippets were adapted from [Conflict EDT](https://github.com/ArthurHoa/conflict-edt/tree/master) (for evidential decision trees construction) and [iBelief](https://github.com/jusdesoja/iBelief_python) (for belief function operations).\n",
"bugtrack_url": null,
"license": null,
"summary": "Iterative Evidential Mistakeness Minimization - Explainable Evidential Clustering",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/victorsouza89/iemm",
"Issues": "https://github.com/victorsouza89/iemm/issues",
"Repository": "https://github.com/victorsouza89/iemm.git"
},
"split_keywords": [
"belief functions",
" evidential decision trees",
" machine learning",
" uncertainty"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "282ff48a17fc9023b549de05b5e755d82fcc3e51915d036dafcbdacb29bbe5cb",
"md5": "d6c143416b060a10d72883e12bdac87c",
"sha256": "5f09b0b5e98550fc8e99e4c5cd905520edc81df160326dd1319a670632f42433"
},
"downloads": -1,
"filename": "iemm-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6c143416b060a10d72883e12bdac87c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21100,
"upload_time": "2025-08-01T19:39:21",
"upload_time_iso_8601": "2025-08-01T19:39:21.780799Z",
"url": "https://files.pythonhosted.org/packages/28/2f/f48a17fc9023b549de05b5e755d82fcc3e51915d036dafcbdacb29bbe5cb/iemm-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a9e523a5d7d7363d9632bfcd60a89fa73fda524ec6d899dd010b78ff1bbeace4",
"md5": "2ed81d055c154aa88fb0c84d3315ba90",
"sha256": "f935d2d6c4119ca905a5a7be58548e90d03207d032d47c3b43d6969c218c97a7"
},
"downloads": -1,
"filename": "iemm-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2ed81d055c154aa88fb0c84d3315ba90",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22539,
"upload_time": "2025-08-01T19:39:22",
"upload_time_iso_8601": "2025-08-01T19:39:22.959835Z",
"url": "https://files.pythonhosted.org/packages/a9/e5/23a5d7d7363d9632bfcd60a89fa73fda524ec6d899dd010b78ff1bbeace4/iemm-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 19:39:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "victorsouza89",
"github_project": "iemm",
"github_not_found": true,
"lcname": "iemm"
}
JSON
