Metadata-Version: 2.4
Name: TCRcloud
Version: 2.0.0
Summary: TCRcloud is an AIRR visualization and comparison tool
Author-email: Eric de Sousa <eric.de.sousa@ki.se>
License-Expression: MIT
Project-URL: Bug Tracker, https://github.com/eriicdesousa/TCRcloud/issues
Project-URL: Homepage, https://github.com/eriicdesousa/TCRcloud
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: airr>=1.5.0
Requires-Dist: kaleido==0.2.1
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: natsort
Requires-Dist: numpy
Requires-Dist: pandas>=2.0
Requires-Dist: plotly<6,>=5.24
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: scikit-bio
Requires-Dist: scikit-learn
Requires-Dist: scipy>=1.3.0
Requires-Dist: wordcloud
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: maintenance
Requires-Dist: glasbey; extra == "maintenance"
Dynamic: license-file

![TCRcloud](https://github.com/eriicdesousa/TCRcloud/raw/main/images/TCRcloud.png)

[![DOI](https://img.shields.io/badge/DOI-10.1186/s12967--025--07619--4-blue.svg)](https://doi.org/10.1186/s12967-025-07619-4)
![PyPI](https://img.shields.io/pypi/v/TCRcloud)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/TCRcloud)
![License](https://img.shields.io/github/license/eriicdesousa/TCRcloud)
![GitHub last commit](https://img.shields.io/github/last-commit/eriicdesousa/TCRcloud)
[![Tests](https://github.com/eriicdesousa/TCRcloud/actions/workflows/tests.yml/badge.svg)](https://github.com/eriicdesousa/TCRcloud/actions/workflows/tests.yml)

## Overview

TCRcloud is an Adaptive Immune Receptor Repertoire (AIRR) visualization and comparison tool. It produces publication-ready plots from AIRR-compliant rearrangement data and can download rearrangements directly from the AIRR Data Commons.

TCRcloud was initially developed for TCR repertoires but is also compatible with BCR repertoires.

## Features

- **Word clouds** of CDR3 amino acid usage, coloured by V gene
- **Radar plots** comparing diversity indices across repertoires
- **V-gene usage plots**
- **2-D and 3-D amino acid composition plots**
- **Repertoire comparison** of V-gene and amino acid usage between repertoires sharing the same chain
- **Download** of rearrangement data from AIRR Data Commons repositories
- Built-in **example data** to try the tool

## Citation

If you use this tool, please cite our paper:

**de Sousa et al., *TCRcloud: a global visualization tool for T‑ and B‑cell receptor transcripts*, Journal of Translational Medicine, 2026.** https://doi.org/10.1186/s12967-025-07619-4


## Requirements

- Python 3.12 or newer
- The Python development headers (e.g. `python3-dev` on Debian/Ubuntu, `python3-devel` on Fedora/RHEL), needed to build some dependencies from source
- Linux or macOS; on Windows, use the Windows Subsystem for Linux (WSL)
- AIRR-compliant rearrangement files (TSV) as input
- Internet access for the `download` and `testdata` commands (they query the AIRR Data Commons)

## Installation

TCRcloud is written in Python and can be installed from PyPI using pip:

    pip3 install TCRcloud

## Quickstart

Download the example repertoire metadata, fetch the matching rearrangement file, and create a word cloud:

    TCRcloud testdata
    TCRcloud download alpharepertoire.airr.json
    TCRcloud cloud alpharepertoire.airr.rearrangements.tsv

The `testdata` command creates `alpharepertoire.airr.json` and `betarepertoire.airr.json` (plus a ready-to-use `legend.json`), `download` fetches `alpharepertoire.airr.rearrangements.tsv` from the AIRR Data Commons, and `cloud` saves one word cloud image per repertoire and chain.

## Usage

TCRcloud provides seven subcommands:

| Command | Description |
| ------- | ----------- |
| `cloud` | Create a CDR3 word cloud coloured by V gene |
| `radar` | Create a radar plot comparing diversity indices |
| `vgenes` | Create a V-gene usage plot |
| `aminoacids` | Create 2-D or 3-D amino acid composition plots |
| `compare` | Compare V-gene and amino acid usage between repertoires sharing the same chain |
| `download` | Download rearrangement files matching an AIRR repertoire metadata file |
| `testdata` | Download example data (subject su008 from Yost et al., 2019) |

### Create a word cloud

    TCRcloud cloud repertoire.airr.rearrangements.tsv

By default TCRcloud colours the CDR3 sequences based on the V gene, using the built-in palette for the selected species (human by default). You can also provide a JSON file that attributes colours in Hex format to specific sequences:

```json
{
  "#FF0000": ["CAVSLPTDSWGKLQF", "CASSLVVADPYQETQYF"],
  "#0000FF": ["CAYRSKGSQGNLIF", "CASSLGGQSGNEQFF"]
}
```

Sequences not present in the JSON file are coloured grey.

To use your custom colours for the word cloud:

    TCRcloud cloud repertoire.airr.rearrangements.tsv -c colours.json

To create a word cloud without a legend:

    TCRcloud cloud repertoire.airr.rearrangements.tsv -l False

Each input file produces one image per repertoire and chain, named `<input>_<repertoire_id>_<chain>.<png|svg>`.

### Create a radar plot comparing diversity indices

    TCRcloud radar repertoire.airr.rearrangements.tsv

By default the legend uses `repertoire_id`, but you can replace it with your own text by providing a JSON file whose keys match the `repertoire_id` values in the rearrangements file:

```json
{
  "PRJNA509910-su008_pre-TRA": "Subject 8 pre-treatment",
  "PRJNA509910-su008_post-TRA": "Subject 8 post-treatment",
  "PRJNA509910-su008_pre-TRB": "Subject 8 pre-treatment",
  "PRJNA509910-su008_post-TRB": "Subject 8 post-treatment"
}
```

To create a radar plot with your desired legend:

    TCRcloud radar repertoire.airr.rearrangements.tsv -c legend.json

To create a radar plot without a legend:

    TCRcloud radar repertoire.airr.rearrangements.tsv -l False

To export the calculated indices from the radar to a text file (`<input>_repertoire_metrics.txt`):

    TCRcloud radar repertoire.airr.rearrangements.tsv -e True

### Diversity indices used in the radar plot

- **Distinct CDR3:** count of the unique CDR3 sequences in the sample
- **D50 Index:** developed by Dr Jian Han, this index represents the percent of dominant and unique T or B cell clones that account for the cumulative 50% of the total CDR3 counted in the sample
- **1 - Gini Coefficient:** the coefficient originally developed by Dr Corrado Gini to represent the wealth inequality within a social group, inverted so that — like every other axis — a higher value means a more diverse repertoire
- **Shannon Index:** originally developed by Dr Claude Shannon to quantify the entropy in strings of text; calculated here using log<sub>2</sub>
- **Gini-Simpson Index:** a transformation of the index originally developed by Dr Edward H. Simpson to measure diversity in an ecosystem
- **Chao1 Index:** originally developed by Dr Anne Chao to estimate richness in an ecological community
- **Pielou Evenness:** developed by Dr Evelyn C. Pielou to measure how evenly distributed the abundances of a community are, calculated as the Shannon Index divided by the logarithm of the number of unique CDR3 sequences

### Create a V-genes plot

    TCRcloud vgenes repertoire.airr.rearrangements.tsv

To export the processed data from the V-genes plot to a CSV file:

    TCRcloud vgenes repertoire.airr.rearrangements.tsv -e True

### Create a 2-D amino acid plot

    TCRcloud aminoacids repertoire.airr.rearrangements.tsv

### Create a 3-D amino acid plot

    TCRcloud aminoacids repertoire.airr.rearrangements.tsv -t True

The 3-D plot also saves an interactive HTML version next to the image.

To export the processed data from the amino acid plot to a CSV file:

    TCRcloud aminoacids repertoire.airr.rearrangements.tsv -e True

### Compare repertoires

Compare all pairs of repertoires that share the same chain within one file:

    TCRcloud compare repertoire.airr.rearrangements.tsv

Or compare the repertoires of two files (still restricted to matching chains):

    TCRcloud compare repertoire1.airr.rearrangements.tsv repertoire2.airr.rearrangements.tsv

The comparison produces V-gene and 3-D amino acid difference plots; use `-e True` to also export the difference tables as CSV files.

### Download AIRR rearrangement files

TCRcloud can download rearrangement files from AIRR-compliant databases (the AIRR Data Commons) based on an AIRR repertoire metadata file. The output is named after the input, e.g. `repertoire.airr.json` produces `repertoire.airr.rearrangements.tsv`:

    TCRcloud download repertoire.airr.json

### Download the test data

TCRcloud provides test data to experiment with the tool. The data is from subject number 8 of Yost et al. (2019) (DOI: [10.1038/s41591-019-0522-3](https://doi.org/10.1038/s41591-019-0522-3)):

    TCRcloud testdata

This creates the `alpharepertoire.airr.json` and `betarepertoire.airr.json` repertoire files (plus a `legend.json` matching their `repertoire_id` values). You can then use the `download` command to get the matching rearrangement files.

## Examples

**TRB CDR3 word cloud**
![Word cloud of TRB CDR3 amino acid sequences coloured by V gene](https://github.com/eriicdesousa/TCRcloud/raw/main/images/beta.png)

**Diversity comparison**
![Radar plot comparing diversity indices across repertoires](https://github.com/eriicdesousa/TCRcloud/raw/main/images/radar.png)

**V-genes plot**
![Surface plot of V-gene usage per repertoire](https://github.com/eriicdesousa/TCRcloud/raw/main/images/vgene.png)

**2-D Amino acid plot**
![2-D bar plot of CDR3 amino acid composition](https://github.com/eriicdesousa/TCRcloud/raw/main/images/2amino.png)

**3-D Amino acid plot**
![3-D bar plot of CDR3 amino acid composition per position](https://github.com/eriicdesousa/TCRcloud/raw/main/images/3amino.png)

**Comparison plots**

![Comparison 1](https://github.com/eriicdesousa/TCRcloud/raw/main/images/comp1.png)
![Comparison 2](https://github.com/eriicdesousa/TCRcloud/raw/main/images/comp2.png)
![Comparison 3](https://github.com/eriicdesousa/TCRcloud/raw/main/images/comp3.png)
![Comparison 4](https://github.com/eriicdesousa/TCRcloud/raw/main/images/comp4.png)

## Troubleshooting

- **Installation fails while building a dependency** — install the Python development headers first (`sudo apt install python3-dev` on Debian/Ubuntu, `sudo dnf install python3-devel` on Fedora/RHEL).
- **Formatting errors** — the input must follow the [AIRR Rearrangement schema](https://docs.airr-community.org/). Files produced by the `download` command are already compliant.
- **Windows** — run TCRcloud inside WSL; native Windows is not supported.
- **Empty or failed downloads** — `download` and `testdata` query public AIRR Data Commons repositories; check your internet connection and retry.

## License

TCRcloud is released under the MIT License. See [LICENSE](https://github.com/eriicdesousa/TCRcloud/blob/main/LICENSE) for details.
