Package 'ECLIPSE'

Determines the true clonotype of each cell

Description

Analyzes scTCR-seq data and returns results in Seurat object. Specifically, chain pairings across the sample are analyzed to predict chains lost to sequencing dropout and to decipher whether cells with >2 total TCR chains are caused by technical artifacts or true biology.

Usage

ECLIPSE(
  seurat_object,
  contig_type = "all",
  contig_folder_paths = NULL,
  contig_file_paths = NULL,
  batch,
  donor,
  group,
  original_barcode,
  format = "Blank",
  detailedEclipseStats = FALSE,
  combineTcrArgs = list(FALSE, FALSE, FALSE, TRUE),
  allowDoubleChains = "both",
  returnFilteredContigs = FALSE,
  verbose = TRUE
)

Arguments

seurat_object	Seurat object that contains scRNA-seq data.
contig_type	tells whether contig_folder_paths or contig_file_paths should be used to read in contig files and how. To provide file paths, this should be "manual". To provide folders, this should be "all" or "filtered" to search for all or filtered contig annotations files.
contig_folder_paths	vector of paths to directories that contain TCR files. If you use this argument, provide either "all" or "filtered" to contig_type. The order should match the numbers provided in batch.
contig_file_paths	vector of TCR file paths. The order should match the numbers provided in batch. The files can have any name, but they must be all_contig_annotations.csv or filtered_contig_annotations.csv format.
batch	name of column in Seurat meta.data. The column should contain integers, not characters, that tell which position in the contig_folder/file_path vectors contains the TCR contigs for the cell.
donor	name of column in Seurat meta.data. The column should contain the donor, regardless of treatment/timepoint/condition.
group	name of column in Seurat meta.data. This column should specify how the final statistics for each clone should be calculated. For example, should they be calculated per sample, per donor, or among all cells? This can and often will be the same column as donor.
original_barcode	name of column in Seurat meta.data. This must contain the original 10X barcode for the cell. Typically this will end with -1, but users should check their TCR contig files to be sure.
format	default is blank. This tells how missing data is stored in the TCR contig files. Current files likely contain "" so "blank" is the default, but if older contig files are used where any missing data is stored as "None", then "None" should be provided here.
detailedEclipseStats	default is FALSE. Provides detailed stats relating to EM assignment in Seurat meta.data for each cell if TRUE.
combineTcrArgs	arguments that are provided to scRepertoire combineTCR. This should be a list of 4 logical elements, with the elements corresponding to the combineTCR arguments. 1 is removeNA, 2 is removeMulti, 3 is filterMulti, 4 is filterNonproductive. If no clonotype can be predicted with high confidence, then combineTCR using these arguments will determine the final clonotype. The default is the combineTCR default where only filterNonproductive is TRUE.
allowDoubleChains	specifies whether 2 alpha chains, 2 beta chains, or either 2 alpha or 2 beta chains are allowed. Default is both.
returnFilteredContigs	specifies if filtered contigs should be returned instead of running the whole ECLIPSE pipeline. Default is FALSE.
verbose	specifies whether to print an important QC graph, a small table, and also notes through the pipeline. Default is TRUE.

Value

A Seurat object with TCR data provided in meta.data.

Examples

data(test_seurat)

files <- system.file("extdata/examples", package = "ECLIPSE")
tcr_paths <- list.files(
                files,
                pattern = "\\.csv.gz$",
                full.names = TRUE)

cd8_tcr <- ECLIPSE(test_seurat,
                    contig_file_paths = tcr_paths,
                    contig_type = "manual",
                    batch = "index",
                    donor = "donor",
                    group = "donor",
                    original_barcode = "Cell_Barcode")

---

Finds clones with 3 total TCR chains and modifies their contigs

Description

Analyzes chain pairings across a sample to find clones with 2 TCR alpha or 2 TCR beta chains. Then, the contigs are modified so that these cells only have 1 alpha and 1 beta contig, with ::: separating each CDR3 sequence. These contigs are then returned.

Usage

findThreeChainClones(contigs, chain, mode = "standard", printStats = TRUE)

Arguments

contigs	tibble of contigs from cellranger all or filtered contig files.
chain	"alpha" or "beta". This tells it whether clones with two of which chain should be looked for.
mode	"standard" is the default, where modified contigs are returned. If "show" is provided, two tables are returned. The first shows the final set of clones with a double chain of one type, and the second shows how/why some of those clones were called as such. The second is pre-filtering, so some clones may not have been called as having 3 total chains in the end.
printStats	specifies whether notes/stats should be printed. Default is TRUE.

Value

a tibble of modified contigs, except if mode show is selected.

Examples

data(post_qc_contigs)

modified_contigs <- findThreeChainClones(
                        contigs = post_qc_contigs,
                        chain = "a")

---

Example Post-QC TCR contigs that would be generated within ECLIPSE and passed to findThreeChainClones.

Description

Example Post-QC TCR contigs that would be generated within ECLIPSE and passed to findThreeChainClones.

Usage

data(post_qc_contigs)

Format

A data frame in the all_contig_annotations.csv format that is produced by cellranger vdj.

Source

Example data

---

Finds and removes doublets from Seurat objects

Description

Filters out cells with excessive numbers of TCR chains and helps set thresholds for RNA counts based on TCR chain count.

Usage

tcrDoubletDetect(
  object,
  filter = TRUE,
  singleChainLimit = 2,
  totalChainLimit = -1,
  showPlots = TRUE,
  verbose = TRUE
)

Arguments

object	Seurat object.
filter	logical statement whether cells should be filtered or not. Default is TRUE.
singleChainLimit	number of alpha or beta chains that is allowed before filtering occurs. Must be a integer, with a default of 2.
totalChainLimit	number of total TCR chains that is allowed before filtering occurs. Must be an integer. Default is no threshold.
showPlots	logical statement that determines whether plots are provided that help set additional filtering thresholds based on RNA counts and TCR chain count. Default is TRUE.
verbose	specifies whether notes should be printed. Default is TRUE.

Value

a Seurat object that is filtered if desired.

Examples

data(test_seurat_with_tcr)

cd8_tcr_filtered <- tcrDoubletDetect(
                            test_seurat_with_tcr,
                            singleChainLimit = 2)

---

Example minimal Seurat object without TCR information.

Description

Example minimal Seurat object without TCR information.

Usage

data(test_seurat)

Format

A Seurat object.

Source

Example data

---

Example Seurat object with TCR information generated by running the ECLIPSE function.

Description

Example Seurat object with TCR information generated by running the ECLIPSE function.

Usage

data(test_seurat_with_tcr)

Format

A Seurat object.

Source

Example data

---

Example small Seurat object without TCR information.

Description

Example small Seurat object without TCR information.

Usage

data(vignette_object)

Format

A Seurat object.

Source

Example data

---