Metadata-Version: 2.4
Name: tirex-tracker
Version: 0.2.22
Summary: Automatic resource and metadata tracking for information retrieval experiments.
Author-email: Maik Fröbe <maik.froebe@uni-jena.de>, Jan Heinrich Merker <heinrich.merker@uni-jena.de>, Tim Hagen <tim.hagen@uni-kassel.de>
Project-URL: Homepage, https://github.com/tira-io/tirex-tracker
Project-URL: Bug Tracker, https://github.com/tira-io/tirex-tracker/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typing-extensions~=4.0
Requires-Dist: importlib-metadata~=8.0
Requires-Dist: importlib-resources~=6.0
Requires-Dist: ipython
Requires-Dist: pyyaml~=6.0
Provides-Extra: tests
Requires-Dist: bandit[toml]~=1.7; extra == "tests"
Requires-Dist: mypy~=1.5; extra == "tests"
Requires-Dist: pandas-stubs~=2.0; extra == "tests"
Requires-Dist: pytest~=8.0; extra == "tests"
Requires-Dist: pytest-cov<8.0,>=5.0; extra == "tests"
Requires-Dist: runnb~=1.0; extra == "tests"
Requires-Dist: ruff<0.16,>=0.9; extra == "tests"
Requires-Dist: types-pyyaml~=6.0; extra == "tests"
Requires-Dist: jupyter~=1.1; extra == "tests"
Provides-Extra: docs
Requires-Dist: mkdocs~=1.6; extra == "docs"
Requires-Dist: mkdocstrings[python]<0.31.0,>=0.28.2; extra == "docs"
Requires-Dist: mkdocs-material~=9.6; extra == "docs"
Requires-Dist: mkdoxy>=1.2; extra == "docs"
Provides-Extra: examples
Requires-Dist: pandas~=2.0; extra == "examples"
Requires-Dist: python-terrier~=0.13.0; python_version <= "3.12" and extra == "examples"
Requires-Dist: pyterrier-anserini<0.3.0,>=0.1.3; python_version >= "3.10" and extra == "examples"
Requires-Dist: pyterrier-pisa~=0.3.0; (python_version <= "3.10" and platform_system != "Darwin") and extra == "examples"
Requires-Dist: seaborn~=0.13.2; extra == "examples"

# TIREx Tracker

[![CI](https://img.shields.io/github/actions/workflow/status/tira-io/tirex-tracker/ci.yml?branch=master&style=flat-square)](https://github.com/tira-io/tirex-tracker/actions/workflows/ci.yml)
[![Maintenance](https://img.shields.io/maintenance/yes/2026?style=flat-square)](https://github.com/tira-io/tirex-tracker/graphs/contributors) [![Code coverage](https://img.shields.io/codecov/c/github/tira-io/tirex-tracker?style=flat-square)](https://codecov.io/github/tira-io/tirex-tracker/) \
[![Release](https://img.shields.io/github/v/tag/tira-io/tirex-tracker?style=flat-square&label=library)](https://github.com/tira-io/tirex-tracker/releases/)
[![Ubuntu](https://img.shields.io/badge/ubuntu-18.04_%7C_20.04_%7C_22.04_%7C_24.04_%7C_25.04-blue?style=flat-square)](https://github.com/tira-io/tirex-tracker/releases/)
[![macOS](https://img.shields.io/badge/macos-13_%7C_14_%7C_15-blue?style=flat-square)](https://github.com/tira-io/tirex-tracker/releases/)
[![Windows](https://img.shields.io/badge/windows-2022_%7C_2025-blue?style=flat-square)](https://github.com/tira-io/tirex-tracker/releases/)
\
[![PyPi](https://img.shields.io/pypi/v/tirex-tracker?style=flat-square)](https://pypi.org/project/tirex-tracker/) [![Python](https://img.shields.io/pypi/pyversions/tirex-tracker?style=flat-square)](https://pypi.org/project/tirex-tracker/) [![Downloads](https://img.shields.io/pypi/dm/tirex-tracker?style=flat-square)](https://pypi.org/project/tirex-tracker/) [![Docs](https://img.shields.io/badge/docs-github%20pages-blue?style=flat-square)](https://tira-io.github.io/tirex-tracker/) \
[![Issues](https://img.shields.io/github/issues/tira-io/tirex-tracker?style=flat-square)](https://github.com/tira-io/tirex-tracker/issues) [![Commit activity](https://img.shields.io/github/commit-activity/m/tira-io/tirex-tracker?style=flat-square)](https://github.com/tira-io/tirex-tracker/commits) [![License](https://img.shields.io/github/license/tira-io/tirex-tracker?style=flat-square)](LICENSE)


The TIREx tracker is a command line tool and API to automatically track resource usage, hardware specifications, and other metadata when running information retrieval experiments.
It can be used easily in [Python applications](#python-api). For more information, refer to the [project's readme](https://github.com/tira-io/tirex-tracker?tab=readme-ov-file#readme).

## Python API

The Python API can be [installed](#pip-dependency) via Pip from [PyPI](https://pypi.org/project/tirex-tracker/).
After installing the package, you can use the TIREx tracker in your [Python](#python-usage).

### Pip Dependency

First, install the TIREx tracker Python package from [PyPI](https://pypi.org/project/tirex-tracker/):

```shell
pip install tirex-tracker
```

### Python Usage

> [!TIP]
> An exhaustive documentation of the TIREx tracker's Python API can be found on [GitHub Pages](https://tira-io.github.io/tirex-tracker/).

Now, you can track the hardware metrics and metadata of your Python code by using the [context manager](https://geeksforgeeks.org/context-manager-in-python/):

```python
from tirex_tracker import tracking

with tracking() as results:
    # Do something...

print(results)
```

Alternatively, you can track the hardware metrics and metadata of a Python function by using the [function decorator](https://geeksforgeeks.org/decorators-in-python/):

```python
from tirex_tracker import tracked

@tracked
def do_something():
    # Do something...

do_something()

print(do_something.results)
```

If you cannot use either the context manager or the function decorator from above, you can manually start and stop the tracking:

```python
from tirex_tracker import start_tracking, stop_tracking

handle = start_tracking()
try:
    # Do something...
finally:
    results = stop_tracking(handle)

print(results)
```

<!-- TODO: Explain parameters. -->

<!-- TODO: ir_metadata export instructions. -->

## Citation

If you find our work useful and reference or use it in a paper, please cite us.

```bibtex
@inproceedings{tirextracker2025,
    author = {Hagen, Tim and Fr{\"o}be, Maik and Merker, Jan Heinrich and Scells, Harrisen and Hagen, Matthias and Potthast, Martin},
    booktitle = {48th International ACM SIGIR Conference on Research and Development in Information Retrieval (SIGIR 2025)},
    month = jul,
    publisher = {ACM},
    title = {{TIREx Tracker: The Information Retrieval Experiment Tracker}},
    year = {2025}
}
```

You can also use the [`CITATION.cff`](https://github.com/tira-io/tirex-tracker/blob/master/CITATION.cff) to generate a citation in other formats.

## License

The TIREx tracker code is licensed under the [MIT License](https://github.com/tira-io/tirex-tracker/blob/master/LICENSE).
If you use the TIREx tracker in your experiments, we would appreciate you [citing](#citation) our paper.

## Abstract

> The reproducibility and transparency of retrieval experiments heavily depends on properly provided information on the experimental setup and conditions. But as manually curating such experiment metadata can be tedious, error-prone, and inconsistent, metadata should be systematically collected in an automatic way—similar to the collection of Python and git-specific settings in the `ir_metadata` reference implementation. To enable a platform-independent automatic metadata collection following the `ir_metadata` specification, we introduce the TIREx tracker: a tool realized via a lightweight C binary, pre-compiled with all dependencies for all major platforms to track hardware configurations, usage of power/CPUs/RAM/GPUs, and experiment/system versions. The TIREx tracker seamlessly integrates into Python, Java, or C/C++ workflows and can be easily incorporated in run submissions of shared tasks, which we showcase for the TIRA/TIREx platform.
