Software Overview

ESGI is a flexible debarcoding tool for single-cell sequencing data. It can be split into two separate steps: demultiplexing the reads and counting the single-cell features. ESGI can be run as a wrapper of these tools, or demultiplex and count can be executed separately for more control.

During the demultiplexing step, the FASTQ reads are split into the elements as defined in the input pattern. Elements are corrected when they fall within the allowed mismatch threshold. If genomic sequences are included, ESGI can call STAR to map these sequences to a reference genome and add the resulting annotation to the demultiplexed reads. The counting step collapses UMIs, generates a single-cell feature matrix, and assigns additional barcoded attributes, like treatment conditions. Alongside the final matrix, ESGI can report qulaity control metrics for both the demultiplexing and counting step.

For more details, run demultiplex, count, or ESGI with the --help flag.

Demultiplex

Demultiplex maps sequencing reads to barcode patterns, where positional pattern elements are used to encode experiment-specific information, like single cell identities, molecular modalities, and experimental conditions. The tool handles simultaneous mapping to multiple barcode patterns, supports pattern elements of varying lengths, and allows for mismatches in the pattern elements arising from insertions, deletions, and substitutions.

Input:

To perform demultiplexing, input yout experimental FASTQ files and define barcode patterns en elements using text files. Also, specify the allowed mismatches for each pattern element as a comma-separated list of integers (e.g. 0,1,1).

Required input parameters:

Pattern element options:

• Barcodes [filename.txt]: Path to text file containing a list of barcode sequences.
• Constant region [ATCG]: Fixed nucleotide sequence.
• UMI [nX]: A unique molecule identifier consisting of n random bases.
• Forward/reverse separator [-]: Use when there is no overlap between forward and reverse reads and you want them to be mapped independently.
• Stop mapping element [*]: stops mapping at this point. This allows you to ignore long, error-prone, or non-informative regions.

The pattern expects the forward read to be in the 5′→3′ direction, while the revere read corresponds to the reverse complement of the pattern. Forward and reverse reads may overlap. If the forward and reverse reads are non-overlapping, the read separator [-] can be applied together with the independent flag, as described in the optional parameters table below.

Example of a barcode pattern called PATTERN consisting of five positional pattern elements:

        -----------------> <-----------------------
PATTERN:[Ab_barcodes.txt][-][BC1.txt][AGCTCATC][10X]
         |                |  |        |         └─── Random element (ten bases)
         |                |  |        └─── Constant element
         |                |  └─── Barcode element encoding single-cell ID
         |                └─── Read separator for forward and reverse read
         └─── Barcode element encoding feature identity

For barcode elements, define the possible sequences for that specific positional element as a comma-separated list.

CTGATC,CGTTGA,GTAGCG,CATCGT

Specify the maximum allowed mismatched for each pattern element using a comma-separated list of integers.

1,0,1,1,0

Optional parameters:

Output:

For every pattern, demultiplex outputs a tab-delimited (TSV) file containing the demultiplexed reads. In this file, every successfully demutliplexed read appears as a row split and aligned according to the elements specified in the pattern. If the pattern includes a DNA element, an additional FASTQ file is generated alongside the TSV file, containing the extracted genomic sequences. These sequences can later be aligned using STAR. In addition, several quality metrics are generated.

Output files:

The tool also reports the alignment performance into three match type categories, expressed as percentages of the total sequencing reads:

• Perfect matches: Reads whose barcodes match completely.
• Moderate matches: Reads that match within the maximum allowed mismatches.
• Mismatches: Reads that cannot be matched given the maximum allowed mismatches.

STAR

Following demultiplexing, the genomic sequences within the FASTQ files are mapped to a reference genome using the STAR (Spliced Transcripts Alignment to a Reference) aligner.

Instructions for downloading reference genomes - like for human (GRCh38) or mice (GRCm38) - along with instructions for generating the required STAR genome indices, are provided in the Multimodal and Spatial application sections, respectively.

Once the genome index is constructed, STAR can perform the allignment to generate the output files for annotation.

Annotate

The annotate step uses the STAR-derived genomic coordinates to assign gene annotations to the reads and merges this information with the final demultiplexed TSV output file.

Count

The count submodule groups the demultiplexed reads by single-cell and feature barcode. By default, identical UMI-tagged entries are collapsed to produce the final counts for each unique cell- feature combination.

Input:

The count module takes as input the pattern-aligned TSV file generated during demultiplexing, along with indexing information. It requires indices of the pattern elements encoding the single-cell, feature, and UMI identities.

Indices follow zero-based counting and correspond to the columns in the pattern-aligned TSV file. In this file, the first column (index 0) is always the read name, folowed by the pattern elements (starting at index 1).

Required parameters:

Optional parameters for annotation:

Barcode sequences within a pattern element can be replaced by labels, such as feature names or single-cell annotations (e.g. experimental conditions). To implement this, provide an annotation file where the entries follow the exact order of the barcode sequences defined in the pattern element.

Example:

Barcode sequences for a pattern element encoding feature identity:

CTGATC,CGTTGA,GTAGCG,CATCGT

Feature names in same order as corresponding barcode sequences:

feature1,feature2,feature3,feature4

Optional parameters for UMI collapsing:

By default, UMI collapsing is enabled using Hamming distance, allowing a single mismatch. Using the parameters below, you can adjust the distance metric, mismatch threshold, or disable collapsing entirely.

Output

After count completes, it creates several output files. The most important are the collapsed and uncollapsed count matrices.

• UMI uncollapsed : Reports the total number of reads per UMI, providing insight into UMI amplification during the PCR experiment.
• UMI collapsed: All reads sharing the same UMI are collapsed to create the final count matrix for each unique cell- feature combination.

ESGI

Instead of running demultiplex and count separately, you can execute them together using ESGI. To do this, you must provide an initialization-file (.ini) containing the essential input, including paths to all pattern files, as well as indexing information. Including feature names and single-cell annotations is optional.

Run esgi --help for a full list of arguments that can be used in the initialization file.

Example of ESGI Initialization-file:

# Input directory
forward="/path/to/forward_reads.fastq.gz"
# Reverse reads (optional)
reverse="/path/to/reverse_reads.fastq.gz"

# Output directory
output="/path/to/output"

# Paths to barcode scheme and mismatch settings
pattern="/path/to/barcode_pattern.txt"
mismatches="/path/to/mismatches.txt"

# Indexes for single-cell, feature, and UMI assignment
SC_ID=1,5
FEATURE_ID=3
UMI_ID=4

# Optional: feature names and single-cell annotations
FEATURE_NAMES="/path/to/feature_names.txt"

ANNOTATION_IDs="/path/to/annotation_ID.txt"
ANNOTATION_NAMES="/path/to/annotation_names.txt"

threads=10
prefix=MYEXPERIMENT