iCAT: Immune Cells Analysis software Tool

Cite this article

Rajeh A, Wolf K, Schiebout C et al. iCAT: diagnostic assessment tool of immunological history using high-throughput T-cell receptor sequencing. F1000Research 2021, 10:65 (https://doi.org/10.12688/f1000research.27214.2).

Summary

High throughput sequencing of immune cell receptor sequences presents a unique opportunity to inform our understanding of immunological response to infection and how we can detect it. iCAT is a user-friendly, graphical-interface software that takes exposed and non-exposed samples of T-cell receptor (TCR) clonotypes as input and identifies pathogen-specific TCR sequences. Using these sequences, iCAT can also classify independent samples of TCR clonotypes. iCAT was able to identify vaccine-associated TCR sequences with up to 95% prediction accuracy in mice.

iCAT GitHub Page: https://biohpc.github.io/iCAT

Pre-requisites

• R version

  • Download R (>3.4.0) version from CRAN.
    • Windows: https://cran.r-project.org/bin/windows/base/
    • Mac OS X: https://cran.r-project.org/bin/macosx/
    • Linux: https://cran.r-project.org/bin/linux/

• Libraries:

  • devtools

To install devtools, use the command:

install.packages("devtools") 

• For Windows Users:
  • Rtools is required if you have a R version >= R 4.0.0 in your Windows system. Please follow the Rtools installing guide to download and install it.

Note: iCAT also uses shiny, shinyjs, data.table, ggplot2, DT, hash, and magrittr. However, those packages will be installed if using install_github from below.

Installing iCAT

Using an R interface, type:

devtools::install_github("BioHPC/iCAT") 

Note: Alternatively, you can clone/download the repository and run devtools::install("iCAT/")

Graphical Interface Workflow

In R:

library(iCAT)
iCATinteractive()

This will launch a graphical user interface (GUI) for iCAT. The GUI has three tabs, separating major functionalities: training, library, and prediction.

Note: If the iCATinteractive() cannot launch the html with an error as "Error in loadNamespace: namespace ‘htmltools’ 0.X.X is already loaded, but >= 0.X.Y is required", please restart the R session.

Training:

1. In the Training tab, enter your negative training samples (naïve, unexposed, pre-infection, etc.) using the Browse button.

Example naive samples included with iCAT can be found in the inst/extdata/Pre/ directory

Individual samples’ sequencing data should be in .tsv format.

2. Repeat step 1 for positive training samples (exposed, infected, etc.)

Example exposed samples included with iCAT can be found in the inst/extdata/Post/ directory

3. Choose if you want to analyze data by:

• CDR3 Amino Acid Sequence (TCRs will need the same CDR3 region to be called ‘Identical’)
• TCRV-CDR3-TCRJ (TCRs will need the same TCRBV segment, CDR3 region, and TCRJ segment to be called ‘Identical’) Recommended
• Nucleic Acid (DNA) (TCRs will need the exact same DNA rearrangements/sequence across TCRBV, CDR3, and TCRJ)
• other (customized column name)

4. Choose the Max p-value, which determines the minimal degree of statistical significance that iCAT will accept as being potentially "associated" with the positive group. Defaults to p < 0.1.

5. Choose the Range of Acceptable Copies per Clonotype, which determines the minimum and maximum number of copies a clonotype must have to be included in the analysis. Enter as a space delimted range. Defaults to 1 99. An example of when this could be useful: in case there is expected artifacts in the processing/data that overestimate the copy number of some clonotypes.

6. Choose the Min Threshold of Public Sequences, which determines the minimum number of training samples a TCR sequence must be observed in to be considered as potentially "associated" with the positive group. Defaults to 1. Recommend setting at 10% of positive training samples. E.g. if there are 30 positive training samples, a recommended minimum threshold is 3.

7. Once all options are selected click Train Model

A progress bar will show on the bottom-right corner to update on the satatus of training. After finishing, the training tab will show some exploratory tables and a figure regarding the training data and the model built, which can all be downloaded to the user's machine. In addition, the library and prediction tab will unlock.

Library:

The Library tab displays a table consisting of the "target associated receptor sequences" (TARS), determined to be statistically associated with exposure to the target/agent/pathogen. The table displays each sequence, number of positive and negative training samples the sequence is present in/absent from, and how statistically associated the sequence is to the positive training data (p-value). The table can be downloaded to the user's computer for further analysis using excel, commandline, etc using the download Table button below the table.

Prediction:

The Prediction tab allows the user to add sequencing data from unknown samples (e.g. not included in the previous training data) for classification as "Positive" or "Negative" and determining the accuracy of the diagnostic assay.

1. Use the Browse button to add samples for prediction. Multiple samples may be uploaded simultaneously.
2. Click Predict Independent Sample.

A table will appear after analysis is complete. The table displays sample names along with the prediction "Positive" (red)/ "Negative" (blue), and displays the ‘%TARS’: the percent of individual sequences from the sample that are included in the TARS library. The prediction results can be downloaded as a table.

R-interface Workflow

After loading iCAT with library(iCAT)

1. Define the parameters you would like to use for building the model:

FIELD <- "aminoAcid vGeneName jGeneName" #"aaSeqCDR3"
COUNT <- "copy"
COPY_RANGE <- "1 99" 
P_CUTOFF <- 0.11
MIN_PUBLIC <- 1

2. Make lists of .tsv Positive and Negative training samples:

listPos <- tsvDir("inst/extdata/Post/")
listNeg <- tsvDir("inst/extdata/Pre/")
       

• optional Collect summary statistics about training samples:

trnStats(listNeg, listPos, FIELD, COUNT, COPY_RANGE)
#>         # Samples # Clonotypes # Unique Sequences
#>Negative         9       101942             281336
#>Positive         9        34158              89150

3. Read in Positive and Negative training samples:

naive <- readTrn(listNeg, FIELD, COUNT, COPY_RANGE, "naive")
vaccs <- readTrn(listPos, FIELD, COUNT, COPY_RANGE, "vacc")     

4. Build a model using the training data:

mod <- train(naive, vaccs, listNeg, listPos, FIELD, COUNT, COPY_RANGE, P_CUTOFF, MIN_PUBLIC, NULL)

• optional Produce a table estimating the classification accuracy of the model:

classMat(mod)

• optional Produce a figure showing % of TCR associated with positve samples in positive and negative samples:

plotHist(mod)

• optional Produce the library of TCR sequences associated with positve samples:

getLib(mod) 

5. Predict sample(s) exposure based on model:

pred(mod, "path/to/unknown-sample", "unknown-sample-label", FIELD, COUNT, COPYRANGE)

Note: If predicting multiple samples, use vectors for paths and labels.