Efficient Plackett-Luce

Efficient Plackett-Luce implements fast, numerically stable learning of Plackett-Luce ranking models for data with arbitrary-sized comparison sets. The project follows the algorithmic ideas of Yeung, Kaiser, and Radicchi (2025) and provides a production-ready Python implementation with strong test coverage and documentation.

Project Highlights

• Fast inference based on Newman's iterative updates with optional Numba acceleration
• Support for full, position-1-breaking, and projected pairwise Plackett-Luce variants
• Utilities for model evaluation, cross-validation, and benchmarking
• Examples and docs covering real-world tournament and survey use cases
• Research artifact archived under paper/ for easy reference

Installation

pip install efficient-plackett-luce

To work from source:

git clone https://github.com/diogoribeiro7/efficient-plackett-luce.git
cd efficient-plackett-luce
pip install -e .

Quick Start

from plackett_luce import PlackettLuceModel

# Each entry is (ranking, weight). Positions earlier in the tuple are better.
hyperedges = [
    (("TeamA", "TeamB", "TeamC"), 1),
    (("TeamB", "TeamA"), 2),
    (("TeamC", "TeamA", "TeamB"), 1),
]

model = PlackettLuceModel(model_type="full")
model.fit(hyperedges)

ranking = model.get_ranking()
probability = model.predict_probability(("TeamA", "TeamB", "TeamC"))

print("Top entities:", ranking[:3])
print("P(TeamA > TeamB > TeamC) =", probability)

More examples are available under examples/, including benchmarking scripts and cross-validation workflows.

Repository Layout

• plackett_luce/ – core library code and public API
• tests/ – pytest suite covering model behavior and utilities
• examples/ – runnable scripts demonstrating typical usage patterns
• docs/ – Markdown documentation for API reference and tutorials
• paper/ – research material, including 2501.16565v1.pdf
• pyproject.toml / Makefile – packaging configuration and development tasks

Documentation & Learning Resources

• docs/index.md – project overview and conceptual background
• docs/examples.md – walk-throughs of end-to-end workflows
• docs/api.md – API reference for the exported symbols

Build the docs locally with any Markdown renderer, or integrate them into a static site generator as needed.

Development Setup

pip install -r requirements-dev.txt
pre-commit install

Handy make targets:

• make format – run Black and isort
• make lint – run static checks (flake8, mypy)
• make test – execute the pytest suite with coverage

Testing

pytest
pytest --cov=plackett_luce
pytest tests/test_core.py::test_fit_convergence

The project maintains high coverage and exercises both synthetic and real-world style datasets.

Research Artifact

The reference paper Efficient inference of rankings from multi-body comparisons (Yeung, Kaiser, Radicchi, 2025) is bundled for convenience at paper/2501.16565v1.pdf. Cite it when referencing the underlying methodology.

Citation

@article{yeung2025efficient,
  title={Efficient inference of rankings from multi-body comparisons},
  author={Yeung, Jack and Kaiser, Daniel and Radicchi, Filippo},
  journal={arXiv preprint arXiv:2501.16565},
  year={2025}
}

Contributing

Issues and pull requests are welcome. Please open a ticket for major changes, run the test suite before submitting, and follow the code of conduct. The CONTRIBUTING.md file describes the full workflow.

License

Distributed under the MIT License. See LICENSE for details.

Contact

• Issues: GitHub issue tracker
• Email: dfr@esmad.ipp.pt
• Paper: arXiv:2501.16565