ranx

<div align="center"> <img src="https://repository-images.githubusercontent.com/268892956/750228ec-f3f2-465d-9c17-420c688ba2bc"> </div> <p align="center"> <!-- Python --> <a href="https://www.python.org" alt="Python"><img src="https://badges.aleen42.com/src/python.svg"></a> <!-- Version --> <a href="https://pypi.org/project/ranx/"><img src="https://img.shields.io/pypi/v/ranx?color=light-green" alt="PyPI version"></a> <!-- Downloads --> <a href="https://pepy.tech/project/ranx"><img src="https://static.pepy.tech/personalized-badge/ranx?period=total&units=international_system&left_color=grey&right_color=blue&left_text=downloads" alt="Download counter"></a> <!-- Docs --> <a href="https://amenra.github.io/ranx"><img src="https://img.shields.io/badge/docs-passing-<COLOR>.svg" alt="Documentation Status"></a> <!-- Black --> <a href="https://github.com/psf/black" alt="Code style: black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg"></a> <!-- License --> <a href="https://lbesson.mit-license.org/"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a> <!-- Google Colab --> <a href="https://colab.research.google.com/github/AmenRa/ranx/blob/master/notebooks/1_overview.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"/></a> </p> <!-- ## 🔥 News - [month day year] -->

⚡️ Introduction

ranx ([raŋks]) is a library of fast ranking evaluation metrics implemented in Python, leveraging Numba for high-speed vector operations and automatic parallelization. It offers a user-friendly interface to evaluate and compare Information Retrieval and Recommender Systems. ranx allows you to perform statistical tests and export LaTeX tables for your scientific publications. Moreover, ranx provides several fusion algorithms and normalization strategies, and an automatic fusion optimization functionality. ranx also have a companion repository of pre-computed runs to facilitated model comparisons called ranxhub. On ranxhub, you can download and share pre-computed runs for Information Retrieval datasets, such as MSMARCO Passage Ranking. ranx was featured in ECIR 2022, CIKM 2022, and SIGIR 2023.

If you use ranx to evaluate results or conducting experiments involving fusion for your scientific publication, please consider citing it: evaluation bibtex, fusion bibtex, ranxhub bibtex.

NB: ranx is not suited for evaluating classifiers. Please, refer to the FAQ for further details.

For a quick overview, follow the Usage section.

For a in-depth overview, follow the Examples section.

✨ Features

Metrics

• Hits
• Hit Rate
• Precision
• Recall
• F1
• r-Precision
• Bpref
• Rank-biased Precision (RBP)
• Mean Reciprocal Rank (MRR)
• Mean Average Precision (MAP)
• Discounted Cumulative Gain (DCG)
• Normalized Discounted Cumulative Gain (NDCG)

The metrics have been tested against TREC Eval for correctness.

Statistical Tests

• Paired Student's t-Test (default)
• Fisher's Randomization Test
• Tukey's HSD Test

Please, refer to Smucker et al., Carterette, and Fuhr for additional information on statistical tests for Information Retrieval.

Off-the-shelf Qrels

You can load qrels from ir-datasets as simply as:

qrels = Qrels.from_ir_datasets("msmarco-document/dev")

A full list of the available qrels is provided here.

Off-the-shelf Runs

You can load runs from ranxhub as simply as:

run = Run.from_ranxhub("run-id")

A full list of the available runs is provided here.

Fusion Algorithms

Name	Name	Name	Name	Name
CombMIN	CombMNZ	RRF	MAPFuse	BordaFuse
CombMED	CombGMNZ	RBC	PosFuse	Weighted BordaFuse
CombANZ	ISR	WMNZ	ProbFuse	Condorcet
CombMAX	Log_ISR	Mixed	SegFuse	Weighted Condorcet
CombSUM	LogN_ISR	BayesFuse	SlideFuse	Weighted Sum

Please, refer to the documentation for further details.

Normalization Strategies

• Min-Max Norm
• Min-Max Inverted Norm
• Max Norm
• Sum Norm
• ZMUV Norm
• Rank Norm
• Borda Norm

Please, refer to the documentation for further details.

🔌 Requirements

python>=3.8

As of v.0.3.5, ranx requires python>=3.8.

💾 Installation

pip install ranx

💡 Usage

Create Qrels and Run

from ranx import Qrels, Run

qrels_dict = { "q_1": { "d_12": 5, "d_25": 3 },
               "q_2": { "d_11": 6, "d_22": 1 } }

run_dict = { "q_1": { "d_12": 0.9, "d_23": 0.8, "d_25": 0.7,
                      "d_36": 0.6, "d_32": 0.5, "d_35": 0.4  },
             "q_2": { "d_12": 0.9, "d_11": 0.8, "d_25": 0.7,
                      "d_36": 0.6, "d_22": 0.5, "d_35": 0.4  } }

qrels = Qrels(qrels_dict)
run = Run(run_dict)

Evaluate

from ranx import evaluate

# Compute score for a single metric
evaluate(qrels, run, "ndcg@5")
>>> 0.7861

# Compute scores for multiple metrics at once
evaluate(qrels, run, ["map@5", "mrr"])
>>> {"map@5": 0.6416, "mrr": 0.75}

Compare

from ranx import compare

# Compare different runs and perform Two-sided Paired Student's t-Test
report = compare(
    qrels=qrels,
    runs=[run_1, run_2, run_3, run_4, run_5],
    metrics=["map@100", "mrr@100", "ndcg@10"],
    max_p=0.01  # P-value threshold
)

Output:

print(report)

#    Model    MAP@100    MRR@100    NDCG@10
---  -------  --------   --------   ---------
a    model_1  0.320ᵇ     0.320ᵇ     0.368ᵇᶜ
b    model_2  0.233      0.234      0.239
c    model_3  0.308ᵇ     0.309ᵇ     0.330ᵇ
d    model_4  0.366ᵃᵇᶜ   0.367ᵃᵇᶜ   0.408ᵃᵇᶜ
e    model_5  0.405ᵃᵇᶜᵈ  0.406ᵃᵇᶜᵈ  0.451ᵃᵇᶜᵈ

Fusion

from ranx import fuse, optimize_fusion

best_params = optimize_fusion(
    qrels=train_qrels,
    runs=[train_run_1, train_run_2, train_run_3],
    norm="min-max",     # The norm. to apply before fusion
    method="wsum",      # The fusion algorithm to use (Weighted Sum)
    metric="ndcg@100",  # The metric to maximize
)

combined_test_run = fuse(
    runs=[test_run_1, test_run_2, test_run_3],  
    norm="min-max",       
    method="wsum",        
    params=best_params,
)

📖 Examples

Name	Link
Overview
Qrels and Run
Evaluation
Comparison and Report
Fusion
Plot
Share your runs with ranxhub

📚 Documentation

Browse the documentation for more details and examples.

🎓 Citation

If you use ranx to evaluate results for your scientific publication, please consider citing our ECIR 2022 paper:

<details> <summary>BibTeX</summary>

@inproceedings{ranx,
  author       = {Elias Bassani},
  title        = {ranx: