Skip to content

Single-cell and spatial transcriptomics

IsoQuant supports single-cell and spatial long-read data obtained using various protocols. When a single-cell or spatial mode is selected, IsoQuant automatically performs barcode calling and UMI-based PCR deduplication as part of the pipeline.

Overview

The single-cell/spatial pipeline extends the standard bulk pipeline with these additional steps:

  1. Barcode calling -- extract cell/spot barcodes and UMIs from raw reads;
  2. Standard IsoQuant processing -- alignment, read-to-isoform assignment;
  3. UMI deduplication -- remove PCR/RT duplicates;
  4. Grouped quantification -- produce per-cell/per-spot gene and transcript counts.

Note: UMI deduplication relies on read-to-gene assignment. Reads that are not assigned to any gene are discarded. Hence, novel gene discovery will not be performed in single-cell/spatial mode. We recommend using bulk mode for novel gene and transcript discovery.

Barcode calling is handled by the built-in barcode calling module, which can also be used as a standalone tool.

Supported protocols

Mode Platform Barcode whitelist files UMI length Notes
tenX_v3 10x Genomics 3' v3 1 12 Single 16bp barcode
tenX_v2 10x Genomics 3' v2 1 10 Single 16bp barcode (v2 chemistry)
tenX_v3_split 10x Genomics 3' v3 1 12 Concatenated reads: splits into individual cDNA molecules
tenX_v2_split 10x Genomics 3' v2 1 10 Concatenated reads: splits into individual cDNA molecules (v2 chemistry)
visium_5prime 10x Genomics Visium 5' 1 12 Same detector as tenX_v3
visium_hd 10x Genomics Visium HD 2 9 Two barcodes (15/16bp + 14/15bp)
curio Curio Bioscience 1 9 Double barcode (8bp + 6bp) with linker
stereoseq Stereo-seq 1 10 25bp barcode, read splitting mode
stereoseq_nosplit Stereo-seq 1 10 25bp barcode, no read splitting
custom_sc Any protocol 0 (uses MDF) varies User-defined molecule structure via MDF file

Quick start examples

10x Genomics single-cell: 

isoquant.py --reference genome.fa --genedb genes.gtf --complete_genedb \
  --fastq reads.fastq.gz --data_type nanopore \
  --mode tenX_v3 --barcode_whitelist barcodes.txt.gz \
  -o sc_output

Stereo-seq spatial: 

isoquant.py --reference genome.fa --genedb genes.gtf --complete_genedb \
  --fastq reads.fastq.gz --data_type nanopore \
  --mode stereoseq --barcode_whitelist barcodes.txt \
  -o stereo_output

Custom protocol with molecule definition file: 

isoquant.py --reference genome.fa --genedb genes.gtf --complete_genedb \
  --fastq reads.fastq.gz --data_type nanopore \
  --mode custom_sc --molecule molecule_definition.mdf \
  -o custom_output

Pre-called barcodes (skip barcode calling): 

isoquant.py --reference genome.fa --genedb genes.gtf --complete_genedb \
  --bam aligned.bam --data_type nanopore \
  --mode tenX_v3 --barcoded_reads barcodes.tsv \
  -o sc_output

Command line options

--mode or -m

IsoQuant processing mode. Available modes:

  • bulk -- standard bulk RNA-seq mode (default)
  • tenX_v3 -- 10x Genomics single-cell 3' gene expression
  • tenX_v2 -- 10x Genomics single-cell 3' v2 gene expression
  • tenX_v3_split -- 10x Genomics 3' v3 with read splitting for concatenated reads (see below)
  • tenX_v2_split -- 10x Genomics 3' v2 with read splitting for concatenated reads
  • curio -- Curio Bioscience single-cell
  • visium_hd -- 10x Genomics Visium HD spatial transcriptomics
  • visium_5prime -- 10x Genomics Visium 5' spatial transcriptomics
  • stereoseq -- Stereo-seq spatial transcriptomics, with read splitting
  • stereoseq_nosplit -- Stereo-seq without read splitting
  • custom_sc -- custom single-cell/spatial mode using a molecule definition file (MDF)

All modes except bulk enable automatic barcode calling and UMI-based deduplication.

--barcode_whitelist

Path to file(s) with barcode whitelist(s) for barcode calling. Required for single-cell/spatial modes unless --barcoded_reads or --barcoded_bam is provided.

File should contain one barcode sequence per line. More than 1 tab-separated column is allowed, but only the first will be used. Supports plain text and gzipped files.

Notes: - Barcode calling is performed much better if the whitelist contains a small number of barcodes. If you have a subset of barcodes from short-read data, provide them instead of the full whitelist; - IsoQuant will perform per-barcode quantification automatically unless --barcoded_reads or --barcode2spot are set. Use --read_group barcode to group reads by barcode explicitly. In case of a large number of barcodes, it may take a lot of time.

The number of whitelist files depends on the mode:

  • 1 file: tenX_v3, tenX_v2, tenX_v3_split, tenX_v2_split, visium_5prime, stereoseq, stereoseq_nosplit, curio (combined 14bp barcodes)
  • 2 files: visium_hd (part 1 and part 2 barcode lists)
  • Not needed: custom_sc (barcode lists are specified inside the MDF file)

--barcoded_reads

Path to TSV file(s) with pre-called barcoded reads. Format: read_id<TAB>barcode<TAB>umi (one read per line). If provided, IsoQuant skips barcode calling and uses these assignments directly. More than 3 columns are allowed, but only the first 3 will be used. Mutually exclusive with --barcode_whitelist and --barcoded_bam.

Note that IsoQuant will perform per-barcode quantification automatically unless --barcoded_reads or --barcode2spot are set. Use --read_group barcode to group reads by barcode explicitly. In case of a large number of barcodes, it may take a lot of time.

--barcoded_bam

Extract barcodes and UMIs from BAM tags. Uses CB (cell barcode) and UB (UMI) tags by default. Mutually exclusive with --barcode_whitelist and --barcoded_reads. This option is a flag, not a way to provide the file (use --bam to set the input BAM).

Note that IsoQuant will perform per-barcode quantification automatically unless --barcoded_reads or --barcode2spot are set. Use --read_group barcode to group reads by barcode explicitly. In case of a large number of barcodes, it may take a lot of time.

--barcode_tag BAM tag for cell barcode (default: CB), requires --barcoded_bam flag.

--umi_tag BAM tag for UMI (default: UB), requires --barcoded_bam flag.

--strip_barcode_suffix Remove suffix after dash from barcodes extracted from BAM tag (e.g. ACGT-1 -> ACGT), requires --barcoded_bam flag.

--barcode2spot

Path to a TSV file mapping barcodes to cell types, spatial spots, or other barcode properties. By default, barcode is in the first column, cell type in the second. However, you can specify one or more columns via colon symbol (similar to --read_group): file.tsv:barcode_column:spot_column(s) (e.g., cell_types.tsv:0:1,2,3 for multiple barcode properties).

When --barcode2spot is set, --read_group barcode_spot will be set automatically to group counts by cell type, spatial regions, or other provided properties. This will also turn off automatic per-barcode grouping (set --read_group barcode to enable).

--molecule

Path to a molecule description format (MDF) file for custom_sc mode. This file defines the structure of the sequencing molecule (barcodes, UMIs, linkers, polyT, cDNA) and allows IsoQuant to process reads from any single-cell or spatial protocol. See the MDF format section below for details.

--barcode2barcode

This option is still under development.

Path to a TSV file with mapping barcodes to spot IDs for spot-level UMI deduplication. When multiple barcodes map to the same physical spot (e.g. at lower spatial resolution), this option groups them together during UMI deduplication, collapsing duplicates across the entire spot (not just the barcode).

Format: file.tsv or file.tsv:barcode_col:spot_col(s) (same syntax as --barcode2spot). When multiple spot columns are provided, a separate UMI deduplication round is performed for each column and outputs corresponding UMI-deduplicated reads only in allinfo format. However, only the main (barcode-based) UMI-deduplicated reads will be used for quantification.

When --barcode2barcode is set, --read_group barcode_barcode will be set automatically. Grouping by raw barcode sequences will be disabled in this case, use --read_group barcode to enable it.

For Visium HD composite barcodes, use isoquant_lib/scripts/prepare_visium_spot_ids.py to generate the mapping file.

Molecule description format (MDF)

The MDF format allows users to describe the structure of their sequencing molecule so that IsoQuant can extract barcodes and UMIs from arbitrary protocol. The molecule is described in the 3' to 5' direction (primer end first, cDNA last).

An MDF file has two parts:

  1. Header line: colon-separated list of element names defining the order of elements on the molecule (3' to 5').
  2. Element definitions: one line per element, tab-separated: name type value [length].

Element types

Type Description Value field
CONST Constant/known sequence (primer, linker, TSO) Sequence
VAR_FILE Variable sequence matched against a whitelist file Path to TSV file
VAR_LIST Variable sequence matched against an inline list Comma-separated sequences
VAR_ANY Variable fixed-length sequence extracted as-is Length (integer)
VAR_ANY_SEPARATOR Fixed-length variable separator sequence (not extracted) Length (integer)
VAR_ANY_NON_T_SEPARATOR Fixed-length variable separator sequence without T nucleotides (not extracted) Length (integer)
PolyT PolyT tail (none)
cDNA cDNA region (none)

Currently, only a single cDNA and a single PolyT are supported. Protocols that concatenate multiple cDNAs (like Kinnex) will be supported in one of the next releases.

Variable elements are expected to have a fixed length (VAR_FILE and VAR_LIST). Using variable-length barcodes may result in suboptimal performance.

Barcode and UMI identification

Elements are identified as barcodes or UMIs by their name prefix (case-insensitive): - Names starting with barcode are treated as barcode elements (e.g., Barcode, barcode1) - Names starting with umi are treated as UMI elements (e.g., UMI, umi1)

When multiple barcode (or UMI) elements are present, their sequences are concatenated in the order they appear.

Examples

10x 3' single-cell v3: 

R1:Barcode:UMI:PolyT:cDNA:TSO
R1        CONST      CTACACGACGCTCTTCCGATCT
Barcode   VAR_FILE   barcodes.tsv
UMI       VAR_ANY    12
TSO       CONST      CCCATGTACTCTGCGTTGATACCACTGCTT

10x 3' single-cell v3 (inline barcodes): 

R1:Barcode:UMI:PolyT:cDNA:TSO
R1        CONST      CTACACGACGCTCTTCCGATCT
Barcode   VAR_LIST   AAACCCGGGTTTAAAC,TTTGGGCCCAAATTTG,GGGGAAAACCCCTTTT
UMI       VAR_ANY    12
TSO       CONST      CCCATGTACTCTGCGTTGATACCACTGCTT

Linked elements for multi-part barcodes

When a barcode is split into multiple parts in the molecule, use linked element notation. All linked parts must be of the same variable type and reference the same whitelist. Parts are numbered consecutively starting from 1.

Concatenated (|): parts of the barcode separated by other elements. Parts are extracted independently, then concatenated and corrected as one sequence against the full whitelist. Such structure appears in, for example, Curio Bioscience single-cell protocol:

PCR_PRIMER:Barcode|1:Linker:Barcode|2:UMI:PolyT:cDNA
PCR_PRIMER  TACACGACGCTCTTCCGATCT
Barcode|1   VAR_FILE   barcodes.tsv   8
Linker      CONST      TCTTCAGCGTTCCCGAGA
Barcode|2   VAR_FILE   barcodes.tsv   6
UMI         VAR_ANY    9

Duplicated (/): multiple redundant copies of the same barcode in the molecule. Each copy is corrected independently against the whitelist; a majority vote determines the final barcode. For example: 

PCR_PRIMER:Barcode/1:UMI:PolyT:cDNA:Barcode/2:TSO
PCR_PRIMER  TACACGACGCTCTTCCGATCT
Barcode/1   VAR_FILE   barcodes.tsv   16
Barcode/2   VAR_FILE   barcodes.tsv   16
UMI         VAR_ANY    12
TSO       CONST      CCCATGTACTCTGCGTTGATACCACTGCTT

Read splitting modes

Oxford Nanopore long reads often contain 2 or more cDNA molecules. Usual non-split modes (tenX_v3, tenX_v2, stereoseq_nosplit) detect only the first barcode and the rest of the read is treated as a single cDNA. The split modes detect multiple barcode/UMI patterns within each read, split the read at molecule boundaries, and produce a new FASTA file with one record per cDNA molecule.

The split modes produce an additional output file (*.split_reads.fasta) containing the extracted cDNA segments. Each segment is named with the original read ID plus coordinates and strand: {read_id}_{start}_{end}_{strand}.

These modes are recommended to use with ONT reads.

UMI deduplication

All single-cell and spatial modes perform UMI-based PCR deduplication after isoform assignment. Within each cell barcode and gene, reads with similar UMIs (similarity criteria depends on the UMI length) are collapsed into a single representative read.

The representative read is selected based on: 1. Unique isoform assignment over ambiguous 2. More exons 3. Longer transcript alignment

The resulting reads after UMI-deduplication are used for the subsequent analysis such as quantification and are stored in a read_info.tsv file.

Spot-level UMI deduplication

When multiple barcodes correspond to the same spatial spot, UMI deduplication can be performed using these spots instead of individual barcodes. In this case, use --barcode2barcode option to provide barcode to spot mapping (see details above).

isoquant.py --reference genome.fa --genedb genes.gtf --complete_genedb \
  --fastq reads.fastq.gz --data_type nanopore \
  --mode visium_hd --barcode_whitelist part1.txt part2.txt \
  --barcode2barcode barcode2spot.tsv:0:1,2 \
  -o visium_output

For Visium HD, generate the mapping file from per-part coordinate files:

python isoquant_lib/scripts/prepare_visium_spot_ids.py part1_to_y.tsv part2_to_x.tsv -o barcode2spot.tsv

Output

Count matrices

Single-cell/spatial modes produce grouped count matrices in addition to the standard IsoQuant output. Use --counts_format to control the output format:

  • default - automatic selection: matrix format for small numbers of groups (<=100), MTX for larger datasets;
  • matrix - standard matrix format with genes/transcripts as rows and barcodes as columns (may take a lot of space for large group numbers);
  • mtx - Matrix Market (MTX) format compatible with Seurat and Scanpy;
  • none - no conversion (only internal linear format is produced);

Grouped counts can also be converted after the run using isoquant_lib/quantification/convert_grouped_counts.py.

Grouping counts

Use --read_group to control how reads are grouped for quantification. Multiple grouping strategies can be combined (space-separated), producing separate count tables for each.

In single-cell/spatial modes, IsoQuant automatically adds --read_group barcode only when --barcoded_reads or --barcode2spot are not set. Use --read_group barcode to group reads by barcode explicitly. In case of a large number of barcodes, it may take a lot of time. Use --read_group no_auto to disable automatic grouping.

The most common use-cases for single-cell/spatial data are grouping by barcode property (cell type, spot):

--read_group barcode_spot (requires --barcode2spot)

--read_group barcode_barcode (requires --barcode2barcode)

or grouping by individual barcode (not recommended for datasets with many barcodes):

--read_group barcode

See the read grouping options for the full list of grouping strategies.