Metadata-Version: 2.4
Name: tcrio
Version: 0.3.0b4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
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: Programming Language :: Python :: 3.14
Requires-Dist: polars>=1.42,<2.0
Requires-Dist: numpy>=2.2
Requires-Dist: scipy>=1.14
Requires-Dist: tqdm>=4.67
Requires-Dist: packaging>=24
Requires-Dist: natsort>=8.4
Requires-Dist: requests>=2.32
Requires-Dist: matplotlib>=3.8
Requires-Dist: seaborn>=0.13
Requires-Dist: networkx>=3.0
Requires-Dist: plotly>=5.0
Requires-Dist: colorcet>=3.0
Requires-Dist: maturin>=1.14 ; extra == 'dev'
Requires-Dist: ruff>=0.15 ; extra == 'dev'
Requires-Dist: pytest>=9.1 ; extra == 'dev'
Requires-Dist: mypy>=2.1 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Polars-based I/O and QC toolkit for T-cell receptor (TCR) repertoire datasets.
Keywords: TCR,immunology,bioinformatics,polars,repertoire
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/vincentvandeuren/tcr_qc

# tcrio

Polars-based I/O and QC toolkit for T-cell receptor (TCR) repertoire datasets.
Fast ingestion of many sequencing formats into a standardized dataset layout,
plus QC operations (filtering, diversity, gene-usage, VDJ statistics, overlap,
HLA inference, CMV hits).

## Install (closed beta)

Beta wheels are attached to GitHub Releases (not on PyPI yet):

```bash
pip install <url-to-the-release-wheel>
```

The wheel bundles the compiled Rust extension and the HLA/CMV model data, so no
build tools or extra downloads are needed.

## Quick start

```python
import tcr_io

# Build a dataset from a directory of repertoire files
ingester = tcr_io.DatasetIngester(
    db_dir="./my_datasets",
    db_name="example",
    repertoire_mapper=tcr_io.FileNameMapper(),
    patient_mapper=tcr_io.FileNameMapper(),
)
ds = ingester.run("path/to/repertoire/files/*.tsv")

# Run a QC operation
from tcr_io.operations import GeneCountsSummary
ds.run_operation(GeneCountsSummary())
print(ds.get_operation_result("gene_counts_summary"))
```

## Dataset layout

A dataset is a directory with this on-disk structure:

```
my_dataset/
├── processed_repertoires/      # One parquet per repertoire. Atomic unit.
│   ├── sample_001.parquet      # Standardized schema, repertoire_id column
│   └── sample_002.parquet
│
├── tabulated/                  # Hive-partitioned. Generated, deletable, rebuildable.
│   ├── v_gene=TRBV7-2/
│   │   └── j_gene=TRBJ2-1/
│   │       └── my_dataset.parquet
│   └── ...
│
├── meta/
│   ├── generation.json         # One row per dataset generation. When, how, source, etc.
│   ├── operations.json         # One row per operation performed on this dataset.
│   ├── repertoire/
│   │   ├── repertoire.parquet       # One row per repertoire. IDs, counts, source files, patient_ids.
│   │   └── repertoire_meta.parquet  # Optional extra metadata (join on repertoire_id).
│   ├── patient/
│   │   ├── patient.parquet           # One row per patient. Aggregated stats.
│   │   ├── patient_meta.parquet      # Optional extra metadata (join on patient_id).
│   │   ├── hla.parquet               # Optional. Known HLA typing.
│   │   └── inferred_hla.parquet      # Optional. Computationally inferred.
│   └── publication/
│       ├── publication_ids.json      # DOI(s) / pubmed_id(s) for associated publications.
│       ├── pdfs/                     # Optional publication PDFs.
│       └── publication.parquet       # Generated, fetched metadata cached here.
│
├── qc/                         # Generated. QC metric tables + plots.
│   ├── repertoire_stats.parquet
│   ├── gene_usage.parquet
│   ├── overlap.parquet
│   └── repertoire_stats.png
│
└── README.md                   # Optional. Auto-generated dataset card.
```

## Bundled models

All model-based operations work out of the box — their reference data ships
inside the wheel and loads automatically with no arguments:

- `HlaInference` / `RepertoireHlaInference` — HLA inference
- `ECOClusterHits` — CMV EcoCluster hits
- `MaitHits` — MAIT hits

Each also accepts `model_checkpoint=<path>` to override with your own model.

## Development

```bash
make venv          # create .venv from requirements.txt (dev lockfile)
make install       # maturin develop (build the Rust extension)
make test          # pytest
make pre-commit    # fmt + clippy + ruff + mypy
```

Bundled resources are generated from raw model sources with
`python scripts/build_resources.py --build` (see `model_sources/README.md`).

