Package: python-terrier
PyTerrierA Python API for Terrier - v.0.10InstallationThe easiest way to get started with PyTerrier is to use one of our Colab notebooks - look for thebadges below.Linux or Google Colab or Windowspip install python-terrierYou may need to set JAVA_HOME environment variable if Pyjnius cannot find your Java installation.macOSYou need to hava Java installed. Pyjnius/PyTerrier will pick up the location automatically.pip install python-terrierIndexingPyTerrier has a number of useful classes for creating indices:You can create an index from TREC formatted collection usingTRECCollectionIndexer.For TXT, PDF, Microsoft Word files, etc files you can useFilesIndexer.For Pandas Dataframe you can useDFIndexer.For any abitrary iterable dictionaries, you can useIterDictIndexer.See theindexing documentation, or the examples in theindexing notebookRetrieval and Evaluationtopics=pt.io.read_topics(topicsFile)qrels=pt.io.read_qrels(qrelsFile)BM25_br=pt.BatchRetrieve(index,wmodel="BM25")res=BM25_br.transform(topics)pt.Evaluate(res,qrels,metrics=['map'])See also theretrieval documentation, or the worked example in theretrieval and evaluation notebookExperiment - Perform Retrieval and Evaluation with a single functionPyTerrier provides anExperimentfunction, which allows to compare multiple retrieval approaches on the same queries & relevance assessments:pt.Experiment([BM25_br,PL2_br],topics,qrels,["map","ndcg"])There is a worked example in theexperiment notebookPipelinesPyTerrier makes it easy to develop complex retrieval pipelines using Python operators such as>>to chain different retrieval components. Each retrieval approach is atransformer, having one key method,transform(), which takes a single Pandas dataframe as input, and returns another dataframe. Two examples might encapsulate applying the sequential dependence model, or a query expansion process:sdm_bm25=pt.rewrite.SDM()>>pt.BatchRetrieve(indexref,wmodel="BM25")bo1_qe=BM25_br>>pt.rewrite.Bo1QueryExpansion()>>BM25_brThere is documentation ontransformer operatorsas well asexample pipelinesshow other common use cases. For more information, see thePyTerrier data model.Neural Reranking and Dense RetrievalPyTerrier has additional plugins for BERT (through OpenNIR), T5, ColBERT, ANCE, DeepCT and doc2query.OpenNIR: [Github] [Documentation]PyTerrier_ANCE: [Github] - dense retrievalPyTerrier_ColBERT: [Github] - dense retrieval and/or neural rerankingPyTerrier_PISA: [Github] - fast in-memory indexing and retrieval usingPISAPyTerrier_T5: [Github] - neural reranking: monoT5, duoT5PyTerrier_doc2query: [Github] - neural augmented indexingPyTerrier_SPLADE: [Github] - neural augmented indexingPyTerrier_DeepCT: [Github] - neural augmented indexingYou can see examples of how to use these, including notebooks that run on Google Colab, in the contents of ourECIR 2021 tutorial.Learning to RankComplex learning to rank pipelines, including for learning-to-rank, can be constructed using PyTerrier's operator language. For example, to combine two features and make them available for learning, we can use the**operator.two_features=BM25_br>>(pt.BatchRetrieve(indexref,wmodel="DirichletLM")**pt.BatchRetrieve(indexref,wmodel="PL2"))See also thelearning to rank documentation, as well as the worked examples in thelearning-to-rank notebook. Some pipelines can be automatically optimised - more detail about pipeline optimisation are included in our ICTIR 2020 paper.Dataset APIPyTerrier allows simple access to standard information retrieval test collections through itsdataset API, which can download the topics, qrels, corpus or, for some test collections, a ready-made Terrier index.topics=pt.get_dataset("trec-robust-2004").get_topics()qrels=pt.get_dataset("trec-robust-2004").get_qrels()pt.Experiment([BM25_br,PL2_br],topics,qrels,eval_metrics)You can index datasets that include a corpus using IterDictIndexer and get_corpus_iter:dataset=pt.get_dataset('irds:cord19/trec-covid')indexer=pt.IterDictIndexer('./cord19-index')index_ref=indexer.index(dataset.get_corpus_iter(),fields=('title','abstract'))You can usept.list_datasets()to see available test collections - if your favourite test collection is missing,you can submit a Pull Request.All datasets from their_datasets packageare available
under theirds:prefix. E.g., usept.datasets.get_dataset("irds:medline/2004/trec-genomics-2004")to get the TREC Genomics 2004 dataset. A full catalogue of ir_datasets is availablehere.Index APIAll of the standard Terrier Index API can be access easily from Pyterrier.For instance, accessing term statistics is a single call on an index:index.getLexicon()["circuit"].getDocumentFrequency()There are lots of examples in theindex API notebookDocumentationMore documentation for PyTerrier is available athttps://pyterrier.readthedocs.io/en/latest/.Open Source LicencePyTerrier is subject to the terms detailed in the Mozilla Public License Version 2.0. The Mozilla Public License can be found in the fileLICENSE.txt. By using this software, you have agreed to the licence.Citation LicenceThe source and binary forms of PyTerrier are subject to the following citation license:By downloading and using PyTerrier, you agree to cite at the undernoted paper describing PyTerrier in any kind of material you produce where PyTerrier was used to conduct search or experimentation, whether be it a research paper, dissertation, article, poster, presentation, or documentation. By using this software, you have agreed to the citation licence.Declarative Experimentation in Information Retrieval using PyTerrier. Craig Macdonald and Nicola Tonellotto. In Proceedings of ICTIR 2020.@inproceedings{pyterrier2020ictir,author={Craig Macdonald and Nicola Tonellotto},title={Declarative Experimentation inInformation Retrieval using PyTerrier},booktitle={Proceedings of ICTIR 2020},year={2020}}CreditsAlex Tsolov, University of GlasgowCraig Macdonald, University of GlasgowNicola Tonellotto, University of PisaArthur Câmara, TU DelftAlberto Ueda, Federal University of Minas GeraisSean MacAvaney, Georgetown University/University of GlasgowChentao Xu, University of GlasgowSarawoot Kongyoung, University of GlasgowZhan Su, Copenhagen UniversityMarcus Schutte, TU Delft