Command-line: Quick Start

Basic usage

1. Inspect input (optional)

[1]:

!head ../../tcrconvert/examples/tenx.csv | column -t -s,

/usr/bin/sh: 1: column: not found
head: write error: Broken pipe

2. Use the convert subcommand

[2]:

!tcrconvert convert \
    --input ../../tcrconvert/examples/tenx.csv \
    --output ../../tcrconvert/examples/converted/tenx2adapt.tsv \
    --frm tenx \
    --to adaptive

Reading input TCR data from: /home/docs/checkouts/readthedocs.org/user_builds/tcrconvert/checkouts/stable/tcrconvert/examples/tenx.csv
Converting gene nomenclature from "tenx" to "adaptive"
WARNING - Adaptive only captures VDJ genes; C genes will be NA.
INFO - Converting from 10X. Using *01 as allele for all genes.
Writing TCR data with converted gene names to: /home/docs/checkouts/readthedocs.org/user_builds/tcrconvert/checkouts/stable/tcrconvert/examples/converted/tenx2adapt.tsv

Explanation of flags used in this command:

  • --input/-i: Input file (CSV or TSV)

  • --output/-o: Output file (CSV or TSV)

  • --frm/-f: Input TCR gene format (tenx, adaptive, adaptivev2, or imgt)

  • --to/-t: Output TCR gene format(tenx, adaptive, adaptivev2, or imgt)

Tip: Suppress INFO-level messages by setting verbose=False. Warnings and errors will still appear.

Tip: If your Adaptive data lacks x_resolved/xMaxResolved columns, create them yourself by combining the x_gene/xGeneName and x_allele/xGeneAllele columns. See the FAQs.

3. Inspect output (optional)

[3]:

!head ../../tcrconvert/examples/converted/tenx2adapt.tsv | column -t

/usr/bin/sh: 1: column: not found
head: write error: Broken pipe

AIRR data

Supply the standard AIRR gene column names individually as custom columns:

  • --custom/-c: Custom gene column name

$ tcrconvert convert -i airr.csv -o out.csv --frm tenx --to imgt \
    -c v_call \
    -c d_call \
    -c j_call \
    -c c_call

Custom column names

By default, TCRconvert assumes these column names based on the input nomenclature (--frm/-f):

  • --frm imgt = ['v_gene', 'd_gene', 'j_gene', 'c_gene']

  • --frm tenx = ['v_gene', 'd_gene', 'j_gene', 'c_gene']

  • --frm adaptive = ['v_resolved', 'd_resolved', 'j_resolved']

  • --frm adaptivev2 = ['vMaxResolved', 'dMaxResolved', 'jMaxResolved']

You can override these columns using the --custom/-c flag:

1. Inspect input 10X data with custom column names (optional)

[4]:

!head ../../tcrconvert/examples/customcols.csv | column -t -s,

/usr/bin/sh: 1: column: not found
head: write error: Broken pipe

2. Convert to IMGT, specifying columns with --custom/-c

[5]:

!tcrconvert convert \
    -i ../../tcrconvert/examples/customcols.csv \
    -o ../../tcrconvert/examples/converted/custom2imgt.csv \
    --frm tenx \
    --to imgt \
    --verbose False \
    -c myVgene \
    -c myDgene \
    -c myJgene \
    -c myCgene

3. Inspect output (optional)

[6]:

!head ../../tcrconvert/examples/converted/custom2imgt.csv | column -t -s,

/usr/bin/sh: 1: column: not found
head: write error: Broken pipe

Rhesus or mouse data

Use the --species/-s flag:

[7]:

!tcrconvert convert \
    -i ../../tcrconvert/examples/tenx.csv \
    -o ../../tcrconvert/examples/converted/tenx2adapt.tsv \
    --frm tenx \
    --to adaptive \
    --verbose False \
    -s rhesus  # or mouse

WARNING - Adaptive only captures VDJ genes; C genes will be NA.
WARNING - These genes are not in IMGT for this species and will be replaced with NA:
 ['TRAV29/DV5', 'TRBV20/OR9-2', 'TRGJ1']