MetaTCR manuscript analysis scripts

This repository contains analysis and panel-plotting scripts supporting the MetaTCR manuscript. FIGURES.md identifies the active entry points for manuscript items reproduced from this repository. The reusable MetaTCR framework is maintained in the separate deepomicslab/MetaTCR repository; the scripts here apply that package to the manuscript datasets and benchmarks.

The repository does not contain the large repertoire datasets, encoded matrices, pretrained model or final multi-panel figure assembly files. Internal experiment logs, parameter-search branches and retired analyses are also outside the public release.

Overview

MetaTCR represents each bulk TCR-beta repertoire as a fixed-length meta-vector over a reference set of functional clusters, so that repertoires from different studies and protocols become directly comparable. The manuscript uses this representation to show that technical and study-of-origin structure persists even within a single clinical label, to benchmark repertoire-profile difference metrics, and to quantify and correct such batch effects through integration — across healthy, autoimmune, infection and cancer cohorts and several focused case studies. The scripts here reproduce those analyses and their figure panels.

Quick start

1. Create an environment compatible with MetaTCR and install the core package:

   git clone https://github.com/deepomicslab/MetaTCR.git
   pip install -e MetaTCR

2. Prepare the data and pretrained model using the layout described in data/README.md. The simplest setup is to link this repository's data/ and pretrained_models/ paths to the corresponding directories in a configured MetaTCR checkout.

3. Select an analysis from FIGURES.md. When separate compute and plotting scripts are listed, run the compute script first. Plotting-only entry points read recorded result tables or Source Data and do not rewrite their analysis inputs. For example:

   python fig_scripts/integration/domain_shift/domain_shift_benchmark.py
   python fig_scripts/integration/domain_shift/domain_shift_plots.py

Scripts derive the repository root from their own location and use repository-relative input and output paths. Run them from the repository root. Generated tables and panel figures are normally written below results/.

Environment

Beyond the core MetaTCR package, the analysis and plotting scripts use a standard scientific-Python stack — PyTorch (repertoire encoding), NumPy, pandas, SciPy and scikit-learn — together with umap-learn and a plotting stack (matplotlib, seaborn). The MetaTCR package does not necessarily install every plotting dependency, so before running the figure scripts please check that umap-learn, matplotlib and seaborn are available in your environment.

Repository layout

Directory	Scope
fig_scripts/dataset_feature_stats/	Raw-repertoire features, overlap and classifier shortcut analyses
fig_scripts/database/	Reference-database summaries
fig_scripts/functional_cluster_num/	Functional-cluster resolution evaluation
fig_scripts/metavec_umaps/	Within-dataset and multi-dataset meta-vector UMAPs
fig_scripts/metavec_evaluation/	Donor-, assay- and repertoire-profile evaluations
fig_scripts/metric_benchmarking/	Repertoire-profile difference metric benchmarks
fig_scripts/case_study/	Wang2022, Emerson CMV and Jurkat analyses
fig_scripts/integration/	Integration simulations, multi-study integration and cross-study transfer

• FIGURES.md maps each displayed panel to its script.

Data and third-party resources

Data archives and their expected locations are documented in data/README.md. Datasets, pretrained models and third-party software remain subject to their respective source terms and licenses.

Citation

If you use this repository, please cite the MetaTCR manuscript:

Citation to be added.

Contact

Questions and bug reports are welcome through the GitHub issue tracker. For other correspondence, contact .

License

The code in this repository is distributed under the GNU General Public License v3.0, consistent with the core MetaTCR software.