py-grex/README.md at d804607e7edaa2c33d7abea19e3981f5fb2eaf3f

admin/py-grex

Fork 0

Files

T

admin 841b6c2b2d Actualizar README.md

2026-06-05 12:10:59 +02:00

5.9 KiB

Raw Blame History

PY-GREX: An Explainable Group Recommender Systems Toolkit

A software toolkit for explainable group recommender systems, including several state-of-the-art explainability methods and evaluation metrics.

➡️ Platform live demo

About

PY-GREX addresses this critical need, offering a modular Python toolkit equipped with multiple state-of-the-art explainability algorithms to facilitate research and development in eXplainable AI (XAI) for Recommender Systems.

🚀 Features

PY-GREX provides a modular, end-to-end pipeline for explainable group recommendations.

Recommendation Models:
- Matrix Factorization:
  - Alternating Least Squares (ALS)
  - Singular Value Decomposition (SVD)
  - Bayesian Personalized Ranking (BPR)
  - Explainable Matrix Factorization (EMF)
- Neural Networks:
  - Generalized Matrix Factorization (GMF)
  - Multi-Layer Perceptron (MLP)
  - Neural Collaborative Filtering (NCF)
  - Deep Autoencoder
- Memory-Based:
  - Item-Based K-Nearest Neighbors
Group Aggregation Strategies:
- Consensus-Based:
  - Additive Utilitarian
  - Multiplicative Utilitarian
  - Average Satisfaction
- Majority-Based:
  - Borda Count
  - Plurality Voting
- Fairness-Oriented:
  - Least Misery
  - Most Pleasure
  - Most Respected Person
Explanation Methods:
- Counterfactual:
  - Sliding Window Explainer (Counterfactual Explanations)
- Rule-Based:
  - EXPGRS (Association Rules Explainer)
- Local Explainers:
  - LORE4Groups (Local Rule-Based Explanations)
Evaluation Metrics:
- Accuracy:
  - Hit Ratio (HR)
  - Normalized Discounted Cumulative Gain (nDCG)
- Explainability:
  - Model Fidelity
  - Gaussian Intra-List Diversity (GILD)
  - Rule Support and Confidence

🏁 Getting Started

Installation

You can install PY-GREX directly using pip:

pip install pygrex

This will install all the required dependencies automatically. PY-GREX requires Python 3.11 or higher.

Local Development

If you want to run the project locally for development:

Prerequisites:
- Python 3.11 or higher
- Git
- Conda (recommended)

Clone the repository:

git clone https://github.com/toledomateus/pygrex.git
cd pygrex

Create and activate a Conda environment:

conda create -n pygrex python=3.11
conda activate pygrex

Install in development mode:
```
pip install -e .
```

This will install the package in development mode, allowing you to modify the source code and see the changes immediately without reinstalling.

Docker

You can use Docker to execute the application. First of all, install Docker on your computer, and then:

Build and run:

docker compose up -d --build

Access the application at:

http://localhost:8501

🎈 Usage

Running Locally

To run the Streamlit app locally:

Install Streamlit:
```
pip install streamlit
```
Run the app:
```
streamlit run Home.py
```

The app will be available at http://localhost:8501

Interactive Web App

The easiest way to use PY-GREX is through the web application. It allows you to:

Upload or use default data for users, items, and groups
Select and train a variety of recommendation models
Generate group recommendations using different aggregation strategies
Produce and evaluate explanations for the recommendations

Jupyter Notebooks

For detailed examples, check out the notebooks in the notebooks/ directory:

expgrs_toy_example.ipynb: Demonstrates the EXPGRS rule-based explainer with association rules
sliding_window_toy_example.ipynb: Shows how to use counterfactual explanations with the Sliding Window method
lore4groups_toy_example.ipynb: Illustrates local rule-based explanations using LORE4Groups

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

📚 Citation

If you use PY-GREX in your research, please cite our paper:

@inproceedings{Toledo2026GREX,
  author    = {Toledo, Mateus and Yera, Raciel and Barranco, Manuel J. and Dutta, Bapi},
  title     = {{GREX}: A Platform for Supporting Explanations in Group Recommender Systems},
  booktitle = {Intelligent Data Engineering and Automated Learning -- {IDEAL} 2025},
  year      = {2026},
  publisher = {Springer Nature Switzerland AG},
  address   = {Cham},
  series    = {Lecture Notes in Computer Science},
  volume    = {16239},
  pages     = {1--13},
  doi       = {10.1007/978-3-032-10489-2_9}
}

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

5.9 KiB Raw Blame History