VEK239 · Oct 4, 2026 · Oct 4, 2026
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -13,7 +13,7 @@ jobs:
           cache: pip
       - run: python -m pip install torch==2.4.1 --index-url https://download.pytorch.org/whl/cpu
       - run: python -m pip install -e ".[dev]"
-      - run: python -m compileall -q src tests
+      - run: python -m compileall -q src
       - run: python -m pytest -q
       - run: rtp-codec --help && rtp-codec train --help && rtp-codec encode --help
-      - run: find scripts -type f \( -name '*.sh' -o -name '*.sbatch' \) -print0 | xargs -0 -n1 bash -n
+      - run: find research/scripts -type f \( -name '*.sh' -o -name '*.sbatch' \) -print0 | xargs -0 -n1 bash -n
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,5 +1,5 @@
 cff-version: 1.2.0
-message: "Please cite the RTP-CODEC manuscript and this repository when using the code."
+message: "Please cite RTP-CODEC, accepted to BioFM @ ICDM'26, and this repository when using the code."
 title: "RTP-CODEC: Learning Compact TCR Representations from Multiple Biological Objectives"
 type: software
 version: 0.1.0

diff --git a/README.md b/README.md
@@ -1,172 +1,58 @@
 # RTP-CODEC
 
-**Learning Compact TCR Representations from Multiple Biological Objectives**
+![RTP-CODEC model: CDR3 sequence, anchor tokenizer, Transformer encoder and three biological objectives](docs/figures/model-schematic.png)
 
-Elizaveta Vlasova, Petr Grigorev, Mariia Demidova, Sergey Muravyov and Mikhail Shugay
+**Learning Compact TCR Representations from Multiple Biological Objectives**<br>
+**Accepted to BioFM @ ICDM'26**
 
-RTP-CODEC learns a **128-dimensional representation of a human TRB CDR3 amino-acid sequence**. A shared Transformer encoder is trained jointly to reconstruct the sequence (**R**), predict TCRemP reference coordinates (**T**), and estimate generation probability (**P**). Once trained, the encoder takes only the CDR3 sequence; TCRemP computation and V/J annotations are needed for training supervision, not for sequence encoding.
+Elizaveta Vlasova · Petr Grigorev · Mariia Demidova · Sergey Muravyov · Mikhail Shugay
 
-This repository contains the model, training pipeline, tokenizers, evaluation tools and result tables accompanying the manuscript *RTP-CODEC: Learning Compact TCR Representations from Multiple Biological Objectives*.
+RTP-CODEC learns a **128-dimensional TRB CDR3 representation** through sequence reconstruction (**R**), TCRemP supervision (**T**) and generation-probability prediction (**P**). After training, encoding requires only the amino-acid sequence.
 
-```mermaid
-flowchart LR
-    S[TRB CDR3 sequence] --> A[DATA-ANCHOR tokenizer]
-    A --> E[Transformer encoder]
-    E --> Z[128-dimensional vector]
-    Z --> R[Sequence reconstruction]
-    Z --> T[TCRemP coordinates]
-    Z --> P[log10 generation probability]
-```
-
-The three heads provide supervision during training. The reusable representation is the encoder output before those heads.
+[Quick start](#quick-start) · [Reproduce the paper](docs/reproduction.md) · [Results](research/results/paper/README.md) · [Documentation](docs/README.md)
 
-## Installation
+## Quick start
 
-Python 3.11 or newer is required. From the repository root:
+Python 3.11+; install from the repository root:
 
 ```bash
-git clone https://github.com/VEK239/rtp-codec.git
-cd rtp-codec
-python -m venv .venv
-# Linux/macOS:
-source .venv/bin/activate
-# Windows PowerShell: .venv/Scripts/Activate.ps1
-python -m pip install --upgrade pip
 python -m pip install -e .
 ```
 
-For a CPU-only environment, install CPU PyTorch before the package:
-
-```bash
-python -m pip install torch==2.4.1 --index-url https://download.pytorch.org/whl/cpu
-python -m pip install -e ".[dev]"
-```
-
-Optional dependencies are grouped by purpose:
-
-| Extra | Purpose |
-| --- | --- |
-| `pgen` | OLGA-backed target generation through the pinned mirpy revision |
-| `benchmarks` | ESM, TCR-BERT and SCEPTR representation comparisons |
-| `tracking` | Weights & Biases logging for earlier training workflows |
-| `notebooks` | Interactive analyses and plots |
-| `dev` | CPU test suite |
-
-For example, `python -m pip install -e ".[pgen,benchmarks,dev]"`. External encoders also require their own model weights; TCRemP requires its separate installation and prototype data. The reported manuscript environment used PyTorch 2.4.1; GPU work additionally requires a compatible CUDA installation.
-
-## Encode sequences
-
-The repository contains source code and result tables. **Trained model weights, tokenizer bundles and the full benchmark data are not bundled here.** Encoding requires a compatible `best.pt` checkpoint and, for DATA-ANCHOR or WordPiece models, its original tokenizer bundle. See [data and model assets](docs/assets.md).
-
-Prepare a TSV with a `junction_aa` column; [examples/data/sequences.tsv](examples/data/sequences.tsv) shows the format. Each sequence must contain standard amino acids and fit the checkpoint's maximum length (40 residues in the manuscript).
+Encode an input TSV with a `junction_aa` column:
 
 ```bash
 rtp-codec encode \
-  --checkpoint artifacts/paper/rtp-seed42/best.pt \
-  --tokenizer data/tokenizers/data_anchor/anchored_tokenizer.json \
-  --input examples/data/sequences.tsv \
-  --output artifacts/example_latents.npy \
-  --device cpu
+  --checkpoint /path/to/best.pt \
+  --tokenizer /path/to/anchored_tokenizer.json \
+  --input research/examples/data/sequences.tsv \
+  --output artifacts/latents.npy
 ```
 
-The output is a float32 NumPy matrix with one vector per input row in the same order, plus a JSON sidecar describing the input and matrix. The vector dimension comes from the checkpoint. `--tokenizer` relocates a saved bundle; it does not retrain or replace the tokenizer. Use `--sequence-column cdr3` for a differently named input column.
-
-The same interface is available in Python:
+This writes one vector per input row, preserving order. Model weights, tokenizer bundles and the locked dataset are separate assets; see [asset requirements](docs/assets.md). Installation options, the Python API and training examples are in the [usage guide](docs/usage.md).
 
-```python
-from rtp_codec.inference import load_encoder
+## Repository
 
-encoder = load_encoder(
-    "artifacts/paper/rtp-seed42/best.pt",
-    tokenizer_path="data/tokenizers/data_anchor/anchored_tokenizer.json",
-    device="cpu",
-)
-vectors = encoder.encode_sequences(["CASSLGQETQYF", "CASSIRSSYEQYF"])
-# vectors.shape == (2, 128) for the manuscript checkpoint
-```
-
-## Train the manuscript model
+| Directory | Contents |
+| --- | --- |
+| [`src/`](src/) | Installable `rtp_codec` library and CPU tests |
+| [`research/`](research/README.md) | Paper configurations, results, launchers, examples and historical notebooks |
+| [`docs/`](docs/README.md) | Usage, reproduction, architecture and migration guides |
 
-The paper uses a locked synthetic TRB dataset of 99,430 unique receptors, split into 79,544 training, 9,943 validation and 9,943 test rows. DATA-ANCHOR edge motifs and target normalizers are fitted on training rows only. Its middle WordPiece vocabulary is trained on a separate 500,000-sequence OLGA corpus with all benchmark sequences excluded. Reconstruction always uses an autoregressive character decoder.
+The diagram above is the original first figure from the final manuscript, rendered for GitHub; its [vector PDF](docs/figures/model-schematic.pdf) is preserved.
 
-Seven matched objective presets live in [configs/paper](configs/paper): `r`, `t`, `p`, `rt`, `rp`, `tp` and `rtp`. Supply the prepared dataset and tokenizer paths:
+## Citation
 
-```bash
-rtp-codec train \
-  --config configs/paper/rtp.json \
-  --data-dir data/benchmark/trb \
-  --tokenizer-path data/tokenizers/data_anchor/anchored_tokenizer.json \
-  --device cuda
-```
+**Accepted to BioFM @ ICDM'26.**
 
-These presets use a 128-dimensional bottleneck, hidden width 320, eight attention heads, four encoder and four decoder layers, batch size 64 and up to 40 epochs. Early stopping is disabled; the checkpoint with the lowest joint validation loss is retained. Command-line arguments override preset values. Training writes `best.pt`, `last.pt`, target normalization statistics, run configuration and evaluation metrics to the configured output directory.
-
-For data preparation, tokenizer construction, the full objective factorial and downstream evaluation, follow [the reproduction guide](docs/reproduction.md). Cluster launchers are described in [docs/cluster.md](docs/cluster.md). A new split or regenerated tokenizer constitutes a new experiment; it should not be presented as an exact reproduction of the locked manuscript runs.
-
-## Results reported in the manuscript
-
-Native heads on the held-out synthetic benchmark:
-
-| Objectives | Reconstruction exact match ↑ | TCRemP cosine ↑ | Pgen RMSE ↓ |
-| --- | ---: | ---: | ---: |
-| R | 0.9766 | — | — |
-| T | — | 0.99149 | — |
-| P | — | — | 0.2753 |
-| RT | 0.9632 | 0.99178 | — |
-| RP | 0.9813 | — | 0.2264 |
-| TP | — | 0.99169 | 0.3496 |
-| RTP | 0.9636 | 0.99190 | 0.2702 |
-
-Source: [matched objective factorial](results/paper/factorial_results.tsv). Pgen means regression of `log10_pgen_1mm`. Dashes indicate inactive objectives. These results show an objective tradeoff: adding T to RP improves teacher agreement while reducing native reconstruction and Pgen performance.
-
-New heads trained on frozen representations provide a separate information-recovery comparison:
-
-| Frozen representation | Reconstruction exact match ↑ | Pgen RMSE ↓ |
-| --- | ---: | ---: |
-| RTP-CODEC | 0.8831 ± 0.0058 | 0.2375 ± 0.0008 |
-| TCRemP | 0.5181 ± 0.0024 | 0.6038 ± 0.0019 |
-| TCR-BERT | 0.4778 ± 0.0179 | 0.4299 ± 0.0022 |
-| ESM2-35M | 0.2042 ± 0.0132 | 0.7086 ± 0.0033 |
-| SCEPTR, CDR3-only | 0.8213 ± 0.0043 | 0.6637 ± 0.0062 |
-
-Source: [consolidated frozen-representation comparison](results/paper/external_author_global_comparison.tsv). Values are mean ± standard deviation across probe seeds; reconstruction uses the common 64-dimensional comparison space. These are fresh probe heads, not the codec's native heads above.
-
-On the independent real VDJdb cohort, RTP-CODEC achieved macro Cohen's d of 0.6866 and improved epitope separation over RP for 31 of 40 epitopes. Native TCRemP and its PCA-128 control remained stronger (0.9563 and 0.8230). The manuscript's single runtime measurements on 68,302 receptors were 29.26 s for RTP-CODEC on CPU, 9.36 s on GPU and 350.25 s for 16-thread TCRemP. Timings exclude loading and warm-up and use different pipeline boundaries; they are hardware-specific, not a general speed guarantee.
-
-The [paper result index](results/paper/README.md) links architecture, tokenizer, downstream and error-analysis tables with their provenance. Earlier benchmark tables are retained in [results/legacy](results/legacy).
-
-## Repository layout
-
-```text
-src/rtp_codec/
-  models/          Shared codec and earlier forward/inverse/Pgen models
-  tokenization/    Character, WordPiece and anchored tokenizers
-  data/            AIRR input, dataset alignment, caches and target generation
-  training/        Trainers, losses, checkpoint handling and tracking
-  inference.py     Checkpoint loading and sequence-to-vector API
-  evaluation/      Shared metric accumulation
-  benchmarks/      Dataset preparation, frozen probes, VDJdb and runtime analyses
-  experiments/     Tokenizer studies, comparison runners and preflight checks
-configs/
-  paper/           Seven manuscript objective presets
-  trb/             Recorded configurations for earlier controlled studies
-scripts/
-  training/        Shell training entry points
-  slurm/           Cluster templates grouped by task
-  legacy/          Earlier experiment launchers
-results/
-  paper/           Manuscript result tables and provenance
-  legacy/          Earlier benchmark results
-examples/data/     Small input examples
-notebooks/         Exploratory and historical notebooks
-tests/            CPU regression and integration tests
-docs/             Reproduction, architecture, assets and migration guides
+```bibtex
+@inproceedings{vlasova2026rtpcodec,
+  title = {RTP-CODEC: Learning Compact TCR Representations from Multiple Biological Objectives},
+  author = {Vlasova, Elizaveta and Grigorev, Petr and Demidova, Mariia and Muravyov, Sergey and Shugay, Mikhail},
+  booktitle = {BioFM @ ICDM'26},
+  year = {2026},
+  note = {Accepted}
+}
 ```
 
-Run `python -m pytest -q` after installing the `dev` extra. The CPU suite includes a small end-to-end training run, tokenizer compatibility checks, dataset alignment, metric checks and checkpoint-based inference. GitHub Actions also checks the public CLI and shell syntax.
-
-## Citation and license
-
-Please cite *RTP-CODEC: Learning Compact TCR Representations from Multiple Biological Objectives* by Elizaveta Vlasova, Petr Grigorev, Mariia Demidova, Sergey Muravyov and Mikhail Shugay. A publication DOI has not yet been added to this repository. [CITATION.cff](CITATION.cff) provides software citation metadata.
-
-The code is distributed under [GNU GPL v3](LICENSE). External models and datasets retain their own licenses.
+Software citation metadata: [CITATION.cff](CITATION.cff). Code license: [GPL v3](LICENSE).
diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,6 @@
 # Documentation
 
+- [Installation, encoding and training](usage.md)
 - [Reproduce the manuscript experiments](reproduction.md)
 - [Model architecture and objectives](architecture.md)
 - [Data, tokenizer and checkpoint assets](assets.md)
@@ -8,6 +9,6 @@
 - [Development and validation](development.md)
 - [Anchored tokenizer study](anchored_tokenizer_study.md)
 - [VDJdb validation protocol](vdjdb_epitope_validation.md)
-- [Earlier benchmark protocols](protocols/)
+- [Earlier benchmark protocols](protocols)
 
-The main results are indexed in [results/paper](../results/paper/README.md). Historical reports and integration provenance are retained under [legacy](legacy/).
+The main results are indexed in [research/results/paper](../research/results/paper/README.md). Historical reports and integration provenance are retained under [legacy](legacy).
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -14,6 +14,6 @@ The DATA-ANCHOR tokenizer uses train-derived edge motifs and a separately traine
 
 Full RTP training assigns weight 1 to each term. Inactive objectives have weight 0. Normalization statistics are fitted only on the training rows. TCRemP and Pgen targets are precomputed; sequence encoding after training does not run either target generator.
 
-Implementation: [codec](../src/rtp_codec/models/codec.py), [objectives](../src/rtp_codec/training/objectives.py), [trainer](../src/rtp_codec/training/multitask.py). The seven [paper presets](../configs/paper/) hold architecture and optimization settings fixed while changing objective weights.
+Implementation: [codec](../src/rtp_codec/models/codec.py), [objectives](../src/rtp_codec/training/objectives.py), [trainer](../src/rtp_codec/training/multitask.py). The seven [paper presets](../research/configs/paper) hold architecture and optimization settings fixed while changing objective weights.
 
-Earlier configurations under `configs/trb` include other bottleneck widths and tokenizer choices. Always load the architecture recorded in a checkpoint rather than substituting the current defaults.
+Earlier configurations under `research/configs/trb` include other bottleneck widths and tokenizer choices. Always load the architecture recorded in a checkpoint rather than substituting the current defaults.
diff --git a/docs/assets.md b/docs/assets.md
@@ -1,6 +1,6 @@
 # Data and model assets
 
-The Git repository distributes code, small format examples, experiment configuration records and result tables. It does not currently distribute the locked dataset, trained model checkpoint, DATA-ANCHOR bundle or a DOI-backed model/data release. Their existing hashes and run locations are recorded in [results/paper/provenance_and_hashes.tsv](../results/paper/provenance_and_hashes.tsv); recorded cluster paths describe past runs and are not public download links.
+The Git repository distributes code, small format examples, experiment configuration records and result tables. It does not currently distribute the locked dataset, trained model checkpoint, DATA-ANCHOR bundle or a DOI-backed model/data release. Their existing hashes and run locations are recorded in [research/results/paper/provenance_and_hashes.tsv](../research/results/paper/provenance_and_hashes.tsv); recorded cluster paths describe past runs and are not public download links.
 
 ## Prepared training dataset
 

diff --git a/docs/cluster.md b/docs/cluster.md
@@ -2,7 +2,7 @@
 
 Install RTP-CODEC into the Python environment used by compute jobs. Submit from the repository root; scheduler partitions, GPU resources and memory limits must match the destination cluster.
 
-The launchers are grouped under `scripts/slurm/{data,training,evaluation,preflight,reports,legacy}`. They preserve earlier experiment conditions and some external asset paths; review those paths before submitting. No jobs are launched merely by installing the package.
+The launchers are grouped under `research/scripts/slurm/{data,training,evaluation,preflight,reports,legacy}`. They preserve earlier experiment conditions and some external asset paths; review those paths before submitting. No jobs are launched merely by installing the package.
 
 The compact manuscript launcher accepts any of the seven paper conditions:
 
@@ -11,9 +11,9 @@ export RTP_CODEC_ROOT="$PWD"
 export RTP_CODEC_PYTHON="$PWD/.venv/bin/python"
 export DATA_DIR=/path/to/locked/trb
 export TOKENIZER_PATH=/path/to/data_anchor/anchored_tokenizer.json
-sbatch scripts/slurm/training/paper.sbatch rtp
+sbatch research/scripts/slurm/training/paper.sbatch rtp
 ```
 
 Change scheduler resource flags with `sbatch --partition=... --gres=...` as appropriate. Logs use the submission directory, and the preset writes results under `artifacts/paper/<condition>-seed42` unless `OUTPUT_DIR` is supplied.
 
-Historical launchers may require preflight manifests, external encoder weights, TCRemP software and existing experiment directories. Their sequence/data gates should be satisfied before full jobs are submitted. Use the [reproduction guide](reproduction.md) and the corresponding [protocol](protocols/) for asset requirements.
+Historical launchers may require preflight manifests, external encoder weights, TCRemP software and existing experiment directories. Their sequence/data gates should be satisfied before full jobs are submitted. Use the [reproduction guide](reproduction.md) and the corresponding [protocol](protocols) for asset requirements.
diff --git a/docs/figures/model-schematic.pdf b/docs/figures/model-schematic.pdf
diff --git a/docs/figures/model-schematic.png b/docs/figures/model-schematic.png