diffir 0.2.0

Tool for visually diffing the difference between two TREC run files.

DiffIR

DiffIR is a tool for visually 'diffing' the difference between two sets of rankings. Given a pair of TREC runs containing rankings for multiple queries, DiffIR identifies contrasting queries that have "substantially" different results between the two systems and generates a visual side-by-side comparison illustrating how the key rankings differ.

DiffIR supports multiple query contrast meastures for ranking comparison including unsupervised ranking correlations like TauAP and supervised comparison based on existing judgments. DiffIR additionally accepts term importance weights in order to highlight the terms most relevant to a model's relevance prediction.

Usage

Installation

Python 3 is required. Install via PyPI:

pip install diffir

Usage

Download two run files to test with:

wget -c https://github.com/capreolus-ir/diffir/raw/master/trec-dl-2020/p_bm25
wget -c https://github.com/capreolus-ir/diffir/raw/master/trec-dl-2020/p_bm25rm3

Compare the two files and output a comparison page to bm25_bm25rm3.html:

diffir p_bm25 p_bm25rm3 -w --dataset msmarco-passage/trec-dl-2020 \
       --measure qrel --metric nDCG@5 --topk 3 > bm25_bm25rm3.html

Now open bm25_bm25rm3.html in your web browser. You should see DiffIR's web interface:

Command line arguments

Usage: diffir <run files> <options> where the run files are 1 or 2 positional arguments indicating the run files to visualize, and <options> are:

• -w to output HTML or -c for the command line interface
• --dataset <id>: a dataset id from ir_datasets
• --measure <measure> the query contrast measure to use. Valid measures: qrel, tauap, pearsonrank, weightedtau, spearmanr, kldiv (using scores)
• --metric <metric>: the relevance metric to use with the qrel measure. Accepts ir_measures notation
• --topk <k>: the number of queries to compare (as identified by the query contrast measure)
• --weights_1 <file>, --weights_2 <file>: term importance files to use for snippet selection

Batch mode

Use diffir-batch to generate comparison pages for every pair of run files in a directory.

Usage: diffir-batch <input directory> -o <output directory> <options> where the <options> are those shown above.