Metadata-Version: 2.1
Name: diffir
Version: 0.2.0
Summary: Tool for visually diffing the difference between two TREC run files.
Home-page: https://github.com/capreolus-ir/diffir
Author: Kevin Martin Jose, Thong Nguyen, Sean MacAvaney, Jeff Dalton, Andrew Yates
Author-email: diffir@googlegroups.com
License: UNKNOWN
Description: 
        [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
        [![Documentation Status](https://readthedocs.org/projects/diffir/badge/?version=latest)](https://capreolus.readthedocs.io/projects/diffir/?badge=latest)
        [![Worfklow](https://github.com/capreolus-ir/diffir/workflows/test/badge.svg)](https://github.com/capreolus-ir/diffir/actions)
        [![PyPI version fury.io](https://badge.fury.io/py/diffir.svg)](https://pypi.python.org/pypi/diffir/)
        [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) 
        
        # 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 [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1MrmY1lKa0Pru--gqAqrcNsilNKZjbm1y/)
        ### 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:
        
        <a href="https://raw.githubusercontent.com/capreolus-ir/diffir/master/docs/images/screenshot.png"><img src="https://raw.githubusercontent.com/capreolus-ir/diffir/master/docs/images/screenshot.png"></a>
        
        ### 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](https://ir-datasets.com/)
        - `--measure <measure>` the query contrast measure to use. Valid measures: qrel, [tauap](https://dl.acm.org/doi/10.1145/1390334.1390435), [pearsonrank](https://dl.acm.org/doi/10.1145/2911451.2914728), [weightedtau](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.weightedtau.html), [spearmanr](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.spearmanr.html), kldiv (using scores)
        - `--metric <metric>`: the relevance metric to use with the qrel measure. Accepts [ir_measures](https://github.com/terrierteam/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.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
