Support homeSpace RangerAnalysis
Space Ranger BAM

Space Ranger BAM

The spaceranger count pipeline outputs an indexed BAM file containing position-sorted reads aligned to the genome and transcriptome, as well as unaligned reads. BAM files can be used for troubleshooting reads that were unaligned or converting BAM files back to FASTQ files.

Each read in this BAM file has Visium spot and molecular barcode information attached. The following assumes basic familiarity with the BAM format. The Type column refers to the type of value stored in the tag (see the SAM/BAM standard) documentation for details.

Although BAM files are generated by default, this behavior can be modified by providing the --no-bam flag to the spaceranger count run.

Important
Space Ranger v2.0 and later, if the slide serial number and capture area were supplied to the Space Ranger count pipeline, they are captured in the BAM file header under the CO tag.

Visium spot and molecular barcode information for each read is stored as TAG fields:

TagTypeDescription
CBZVisium spot barcode sequence that is error-corrected and confirmed against a list of known-good barcode sequences.
CRZVisium spot barcode sequence as reported by the sequencer.
CYZVisium spot barcode read quality. Phred scores as reported by the sequencer.
UBZVisium molecular barcode sequence that is error-corrected among other molecular barcodes with the same spot barcode and gene alignment.
URZVisium molecular barcode sequence as reported by the sequencer.
UYZVisium molecular barcode read quality. Phred scores as reported by the sequencer.
BCZSample index read.
QTZSample index read quality. Phred scores as reported by the sequencer.
TRZTrimmed sequence. Trailing sequence (if any) following the spot and molecular barcodes on Read 1.

The spot barcode CB tag includes a suffix with a dash separator followed by a number:

AACACTTGGCAAGGAA-1

This number will always be one (1) in the current Space Ranger output.

The following tags are also present on reads that mapped to the genome and overlapped an exon by at least one base pair. Reads aligned to the transcriptome across exon junctions in the genome have a large gap in its CIGAR string, such as 35M225N64M. A read may align to multiple transcripts and genes, but it is only considered confidently mapped to the transcriptome if it mapped to a single gene. Note that the BAM files contain all UMIs, including those mapped to barcodes outside of tissue, unlike the filtered matrices. Space Ranger modifies MAPQ values; see the MM tag below.

TagTypeDescription
TXZPresent in reads aligned to the same strand as the transcripts in this semicolon-separated list that are compatible with this alignment. Transcripts are specified with the transcript_id key in the reference GTF attribute column. The format of each entry is [transcript_id],[strand],[pos],[cigar]. strand is + as reads with this annotation were correctly aligned in the expected orientation (in contrast to the AN tag below, where the strand is - to indicate antisense alignments). pos is the alignment offset in transcript coordinates, and cigar is the CIGAR string in transcript coordinates.
ANZSame as the TX tag, but for reads that are aligned to the antisense strand of annotated transcripts i.e. with - values for the strand identifier.
GXZSemicolon-separated list of gene IDs that are compatible with this alignment. Gene IDs are specified with the gene_id key in the reference GTF attribute column.
GNZSemicolon-separated list of gene names that are compatible with this alignment. Gene names are specified with gene_name key in the reference GTF attribute column.
MMiSet to 1 if the genome-aligner (STAR) originally gave a MAPQ < 255 (it multi-mapped to the genome) and Space Ranger changed it to 255 because the read overlapped exactly one gene.
REASingle character indicating the region type of this alignment (E = exonic, N = intronic, I = intergenic).
prZFor Visium FFPE, a semicolon-separated list of probe IDs: one probe ID if both read halves align to the same probe, and two probe IDs if each read half aligns to a different probe, or NA if a read half does not align to a probe.
paiThe number of poly-A nucleotides trimmed from the 3' end of read 2. Up to 10% mismatches are permitted.
tsiThe number of template switch oligo (TSO) nucleotides trimmed from the 5' end of read 2. Up to 3 mismatches are permitted. The 30-bp TSO sequence is AAGCAGTGGTATCAACGCAGAGTACATGGG.
xfiExtra alignment flags. The bits of this tag are interpreted as follows: 1 - The read is confidently mapped to the transcriptome. 2 - The read maps to a feature that the majority of other reads with this UMI did not. 4 - This read pair maps to a discordant pair of genes, and is not treated as a UMI count. 8 - This read is representative of a molecule and is treated as a UMI count. 16 - This read maps to exactly one feature and is identical to bit 1 for transcriptomic reads. Notably, this bit is set for a feature barcode read, while bit 1 is not. 32 - This read was not analyzed due to high sequencing depth and subsampling for Targeted Spatial Gene Expression.

Some aspects of the BAM file are particular to formalin fixed paraffin embedded (FFPE) samples.

A read that multimaps to the reference transcriptome, but maps uniquely to a single probe, is confidently mapped to that probe and its gene. The mapping quality has the following meaning:

MAPQDescription
255Both read halves map to the same probe.
3Each read half maps to a different probe.
1One read half maps to a probe and the other half does not.
0Neither read half maps to a probe.

The BAM tag pr:Z represents the value of the probe_id in the probe_set.csv file. In addition, the BAM tag fx:Z represents the feature identifier which for FFPE Gene Expression has the same value as GX:Z tag, i.e., the gene ID.

Space Ranger v2.1 introduced support for Protein Expression. Sequencing data passed in as a Protein Expression library type is not aligned to the genome. The BAM file will contain unaligned records for these reads, with the following tags representing the Antibody Barcode sequence extracted from the read, and the feature reference it was matched to, if any. The BAM read sequence will contain all the bases outside of the spot barcode and UMI regions.

TagTypeDescription
fbZVisium Antibody Barcode sequence that is error-corrected and confirmed against known feature barcode sequences from the feature reference.
frZVisium Antibody Barcode sequence as reported by the sequencer.
fqZVisium Antibody Barcode read quality. Phred scores as reported by the sequencer.
fxZFeature identifier matched to this Antibody Barcode read. Specified in the id column of the feature_reference.csv file.