RIOT - Rapid Immunoglobulin Overview Tool

Have some raw antibody sequences? Find matching germlines, perform numbering and get results in a familiar AIRR format!

RIOT supports both nucleotide and amino acid sequences as well as all major schemes: KABAT, CHOTHIA, MARTIN and IMGT.

Links:

• PyPI
• Source code
• Collab example

Requirements

• Python ^3.10
• C compiler (reason: scikit-bio)

Quickstart

> pip install riot-na

> riot_na -s GGGCGTTTTGGCAC...

{
    "sequence_header": "-",
    "sequence": "GGGCGTTTTGGCAC...",
    "numbering_scheme": "imgt",
    "locus": "igh",
    "stop_codon": False,
    "vj_in_frame": True,
    "v_frameshift": False,
    "j_frameshift": False,
    "productive": True,
    "rev_comp": False,
    "complete_vdj": True,
    "v_call": "IGHV1-69*01",
    "d_call": "IGHD3-3*01",
    "j_call": "IGHJ6*02",
    "c_call": "IGHM",
    "v_frame": 0,
    ...
}

Installation

Riot is distributed in prebuild binary wheels for all major platforms. Just run in your chosen virtualenv:

pip install riot-na

Usage

CLI

Usage: riot_na [OPTIONS]

Options:
  -f, --input-file PATH           Path to input FASTA file.
  -s, --sequence TEXT             Input sequence.
  -o, --output-file PATH          Path to output CSV file. If not specified,
                                  stdout is used.
  --scheme [KABAT|CHOTHIA|IMGT|MARTIN]
                                  Which numbering scheme should be used: IMGT,
                                  KABAT, CHOTHIA, MARTIN. Default IMGT
  --species [HOMO_SAPIENS|MUS_MUSCULUS|CUSTOM]
                                  Which species germline sequences should be
                                  used. Default is all species.
  --input-type [NT|AA]            What kind of sequences are provided on
                                  input. Default is nucleotide sequences.
  -p, --ncpu INTEGER              Number of parallel processes to use. Default
                                  is number of physical cores.
  -e, --extend_alignment BOOLEAN  Include unaligned beginning of the query
                                  sequence in numbering.This option impacts
                                  only amino acid sequences passed with -s option.
  --multiple-domains BOOLEAN      Return all domains of multiple domain
                                  proteins.
  --help                          Show this message and exit.

Examples:

Run on single sequence and print output to stdout:

riot_na -s <sequence>

Run on single sequence and save output to csv:

riot_na -s <sequence> -o result.csv

Run on fasta file:

riot_na -f input.fasta -o results.csv

API Nucleotides

from riot_na import create_riot_nt, Organism, Scheme, RiotNumberingNT, AirrRearrangementEntryNT

riot_nt: RiotNumberingNT = create_riot_nt(allowed_species = (Organism.HOMO_SAPIENS,))
airr_result: AirrRearrangementEntryNT = riot_nt.run_on_sequence(
                    header = "SRR13857054.957936",
                    query_sequence = "GAACCAAACTGACTGTCCTAGGCCAGCCCAAGTCTTCGCCATCAGTCACCCTGTTTCCACCTTCCCCTGAAGAGCTAAAAAAA",
                    scheme = Scheme.KABAT
                )

API Amino Acids

from riot_na import create_riot_aa, Organism, Scheme, RiotNumberingAA, AirrRearrangementEntryAA

riot_aa: RiotNumberingAA = create_riot_aa(allowed_species = (Organism.HOMO_SAPIENS,))
airr_result: AirrRearrangementEntryAA = riot_aa.run_on_sequence(
                    header = "SRR13385915.5101835",
                    query_sequence = "QVTLKESGPVLVKPTETLTLTCTVSGFSLSNARMGVSWIRQPPGKALEWLAHIFSNDEKSYSTSLKSRLTISKDTSKSQVVLTMTNMDPGDTATYYCARRGGTIFGVVIILVRRPPL",
                    scheme = Scheme.KABAT,
                    extend_alignment = True
                )

Caching

We provide two cached wrappers for create_riot_nt() and crate_riot_aa() functions - get_or_create_riot_nt() | get_or_create_riot_aa(). They can be used exactly the same way as base functions:

from riot_na import get_or_create_riot_aa, Organism, Scheme, RiotNumberingAA, AirrRearrangementEntryAA

riot_aa: RiotNumberingAA = get_or_create_riot_aa(allowed_species = (Organism.HOMO_SAPIENS,))
airr_result: AirrRearrangementEntryAA = riot_aa.run_on_sequence(
                    header = "SRR13385915.5101835",
                    query_sequence = "QVTLKESGPVLVKPTETLTLTCTVSGFSLSNARMGVSWIRQPPGKALEWLAHIFSNDEKSYSTSLKSRLTISKDTSKSQVVLTMTNMDPGDTATYYCARRGGTIFGVVIILVRRPPL",
                    scheme = Scheme.KABAT,
                    extend_alignment = True
                )

Multiprocessing

Riot uses precompiled Rust module for prefiltering. This means the RiotNumberingNT/AA objects are unpickable, so you cannot pass it as a worker's parameter in eg. mp.Pool() or use it in Spark's UDF functions. This is achievable by using cached wrappers we provide get_or_create_riot_nt() | get_or_create_riot_aa(). Below you can find working and not working examples.

The following will not work:

import functools
import multiprocessing as mp
from riot_na import create_riot_aa, AirrRearrangementEntryAA, RiotNumberingAA

seqs = ["EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCARGGSFYYYYMDVWGQGTLVTVSSASTKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSGLYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEPKSCDKTGHHHHHHHHG"] * 10

def worker(riot: RiotNumberingAA, seq: str) -> AirrRearrangementEntryAA:
    airr = riot.run_on_sequence("-", seq)
    return airr

riot = create_riot_aa()

worker_partial = functools.partial(worker, riot)

with mp.Pool() as pool:
    res = pool.map(worker_partial, seqs)

# Output: TypeError: cannot pickle 'builtins.Prefiltering' object

The proper way:

import multiprocessing as mp
from riot_na import get_or_create_riot_aa, AirrRearrangementEntryAA

seqs = ["EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCARGGSFYYYYMDVWGQGTLVTVSSASTKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSGLYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEPKSCDKTGHHHHHHHHG"] * 10


def worker(seq: str) -> AirrRearrangementEntryAA:
    riot = get_or_create_riot_aa()
    airr = riot.run_on_sequence("-", seq)
    return airr

with mp.Pool() as pool:
    res = pool.map(worker, seqs)

Spark UDF example:

import json
from pyspark.sql import SparkSession
from pyspark.sql.functions import udf
from cachetools import cached
from riot_na import get_or_create_riot_aa, RiotNumberingAA

spark = SparkSession.builder.appName("Riot on Spark").getOrCreate()

seq = "EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCARGGSFYYYYMDVWGQGTLVTVSSASTKGPSVFPLAPSSKSTSGGTAALGCLVKDYFPEPVTVSWNSGALTSGVHTFPAVLQSSGLYSLSSVVTVPSSSLGTQTYICNVNHKPSNTKVDKKVEPKSCDKTGHHHHHHHHG"

df = spark.createDataFrame([{"seq":  seq}]*10)

@udf
def number_sequence(seq: str)-> str:
    riot = get_or_create_riot_aa()
    airr = riot.run_on_sequence("-", seq)
    return json.dumps(airr.__dict__)

df.select(number_sequence("seq")).collect()

For a pure Python solution (without the use of cachetools package) you can check riot_na/api/api_mp.py file.

Multidomains support

RIOT's multidomains support allows detection and numbering of multiple immunoglobulin domains within a single protein sequence, such as therapeutic antibodies containing both heavy chain (VH) and light chain (VL) domains. When enabled with the --multiple-domains flag (or return_all_domains=True in the API), RIOT returns separate numbering results for each detected domain rather than just the best single match. The system automatically identifies domain boundaries, truncates sequences at the beginning of each V gene segment, and provides additional metadata including the original query sequence and segment start/end positions for each domain. This is particularly useful for analyzing therapeutic constructs like bispecific antibodies, CAR-T constructs, or other multi-domain fusion proteins where each immunoglobulin domain needs independent numbering and analysis.

Germline database

RIOT uses OGRDB as a primary source of germline alleles. Database version as of 22.01.2024 was used. C genes are imported from igblast FTP site fhttps://ftp.ncbi.nih.gov/blast/executables/igblast/release/database/ncbi_human_c_genes.tar

Data format

This section describes the fields of numbering result object AirrRearrangementEntry(AA). It is based on AIRR Rearrangement Schema format extended by 7 columns highlighted in the table (bold) and emptied of the unnecessary ones. There are also some differences in fields’ definitions, so the AIRR format specification should be treated only as a loose reference. Description of the original AIRR format can be found here.

Attributes:

1. All fields in the format are required (always present)
2. All fields are nullable, with the exception of sequence_header and sequence

AirrRearrangementNT fields definitions

Additional validation flags

Following table describes additional validation flags calculated alongside main fields. Last 5 flags regarding conserved residues apply only then using IMGT schema.

AirrRearrangementAA field definitions

Airr data format was developed for nucleotide sequences. For the amino acid pipeline a similar to format was created. Most fields are analogous to nucleotide-based one, with _aa suffix in name.

Additional validation flags (AA)

Following table describes additional validation flags calculated alongside main fields. Last 5 flags regarding conserved residues apply only then using IMGT schema.

Examples

Sample usage of the software is presented at https://colab.research.google.com/drive/1xKO4udsX5gmnY88eDKWsQaUnHsLuFwVA?usp=sharing. To give users the ability to use RIOT with a custom database, we provide google colab script which showcases how to build a custom germline database for RIOT. It is available at https://colab.research.google.com/drive/1VCStUKgZ1ggi2Xf5YV7hFWHxxzP29BjK?usp=sharing.

Development

RIOT uses prefiltering module written in Rust, which requires some extra steps to install from source.

# Install Poetry

curl -sSL https://install.python-poetry.org | python3 - --version 1.7.1

# Add `export PATH="/root/.local/bin:$PATH"` to your shell configuration file.****

# Download and run the Rust installation script
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# Restart shell to reload PATH

# Verify the installation
!poetry --version
!rustc --version
!cargo --version

git clone https://github.com/NaturalAntibody/riot_na
cd riot_na

poetry install
poetry run maturin develop -r
poetry install

Citing this work

The code and data in this package is based on the following paper <we release the paper once it clears peer review>. If you use it, please cite:

@misc{riot,
      title={RIOT - Rapid Immunoglobulin Overview Tool - rapid annotation of nucleotide and amino acid immunoglobulin sequences using an open germline database.},
      author={Paweł Dudzic, Bartosz Janusz, Tadeusz Satława, Dawid Chomicz, Tomasz Gawłowski, Rafał Grabowski, Przemysław Jóźwiak, Mateusz Tarkowski, Maciej Mycielski, Sonia Wróbel, Konrad Krawczyk*},

}