Install & Compatibility
Where this runs
tested against v2.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.017s · 90.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.6s · import 0.015s · 87MB
90MB installed
● package 90MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
iter_annotations
✓ from trec_car.read_data import iter_annotations
iter_paragraphs
✓ from trec_car.read_data import iter_paragraphs
Page
✓ from trec_car.read_data import Page
Paragraph
✓ from trec_car.read_data import Paragraph
This quickstart demonstrates how to read TREC CAR annotation and paragraph files using `iter_annotations` and `iter_paragraphs` functions. It assumes the dataset files are available locally. The code iterates through the first few pages and paragraphs to show their IDs, names, and text content.
import os
from trec_car.read_data import iter_annotations, iter_paragraphs
# Assuming 'train.test200.cbor' and 'train.test200.cbor.paragraphs' are available locally
# You would typically download these from the TREC CAR website
# Example 1: Reading annotations (pages file)
annotations_file = os.environ.get('TREC_CAR_ANNOTATIONS_FILE', 'train.test200.cbor')
if os.path.exists(annotations_file):
print(f"\nReading page IDs from {annotations_file}:")
with open(annotations_file, 'rb') as f:
for page in iter_annotations(f):
print(f"Page ID: {page.pageId}, Page Name: {page.pageName}")
# Print first 2 pages only for brevity
if page.pageId and page.pageName: break
else:
print(f"\nSkipping annotation reading: {annotations_file} not found.")
# Example 2: Reading paragraphs file
paragraphs_file = os.environ.get('TREC_CAR_PARAGRAPHS_FILE', 'train.test200.cbor.paragraphs')
if os.path.exists(paragraphs_file):
print(f"\nReading paragraph text from {paragraphs_file}:")
with open(paragraphs_file, 'rb') as f:
for para in iter_paragraphs(f):
print(f"Paragraph ID: {para.paragraphId}, Text: {para.getText()[:100]}...")
# Print first 2 paragraphs only for brevity
if para.paragraphId and para.getText(): break
else:
print(f"\nSkipping paragraph reading: {paragraphs_file} not found.")
Debug
Known issues
gotchaData format versions for TREC CAR datasets can change between releases. Ensure you use a version of `trec-car-tools` compatible with your specific dataset version.fixAlways check the TREC CAR website (trec-car.cs.unh.edu) for the recommended `trec-car-tools` version or branch corresponding to the dataset you are using. Older tools might not correctly parse newer data formats, and vice-versa.
affects: All versions
gotchaAnaconda users should install the `cbor` dependency from the `laura-dietz` channel for Python 3.6 to ensure compatibility.fixUse `conda install -c laura-dietz cbor=1.0.0` instead of `pip install cbor` or `conda install cbor` if encountering issues with CBOR data processing in an Anaconda environment.
affects: All versions, specifically Python 3.6+ with Anaconda
gotchaThe GitHub issue tracker indicates several open issues, some of which suggest potential data parsing or consistency problems within the tools, such as `flat_headings_list is not flat` or `v2.0 dataset para id in manual qrels not found in paragraphCorpus`.fixBe aware of these known issues, especially when processing specific dataset versions or structures. Refer to the GitHub issues page (github.com/TREMA-UNH/trec-car-tools/issues) for updates or workarounds.
affects: All versions (potential for certain data formats)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'car'
The `trec-car-tools` library, which provides the `car` package, is not installed in the current Python environment or the environment is not activated.
fixpip install trec-car-tools
ModuleNotFoundError: No module named 'trec_car_tools'
Developers often guess the import name based on the PyPI package name (`trec-car-tools`), but the actual top-level package inside the library is named `car`.
fixUse `import car` or `from car import read_data` instead.
AttributeError: module 'car' has no attribute 'iter_annotations'
The function `iter_annotations` is located within the `read_data` submodule, not directly under the main `car` package.
fixAccess the function using its full path: `car.read_data.iter_annotations`, or import it specifically: `from car.read_data import iter_annotations`.
cbor.CBORError: Data is not valid CBOR format
The input file provided to a `trec-car-tools` function (e.g., `iter_annotations` or `iter_paragraphs`) is corrupted, not a valid CBOR file, or not in the expected TREC CAR CBOR format.
fixEnsure the input `.cbor` file is valid and correctly generated or downloaded. Check its integrity or try with a known good TREC CAR CBOR dataset.
Upgrade
Version history
2.6latest on PyPI · released Feb 1, 2022
Audit
Dependencies
cborrequiredRequired for handling CBOR formatted data. For Anaconda users, a specific version and channel is recommended.