
<LinkableSection id={"alignment"} title={"Alignment"}>

The key read processing steps for genome and transcriptome alignment are detailed below.

</LinkableSection>

<LinkableSection id={"trimming"} nested={true} title={"Read trimming"}>

A full length cDNA construct is flanked by the 30 bp template switch oligo (TSO) sequence, `AAGCAGTGGTATCAACGCAGAGTACATGGG`, on the 5' end and poly-A on the 3' end. Some fraction of sequencing reads are expected to contain either or both of these sequences, depending on the fragment size distribution of the sequencing library. Reads derived from short RNA molecules are more likely to contain either or both TSO and poly-A sequence than longer RNA molecules.

Since the presence of non-template sequence in the form of either template switch oligo (TSO) or poly-A, low-complexity ends confound read mapping, TSO sequence is trimmed from the 5' end of read 2 and poly-A is trimmed from the 3' end prior to alignment. Trimming improves the sensitivity of the assay as well as the computational efficiency of the software pipeline.

Tags `ts:i` and `pa:i` in the output BAM files indicate the number of TSO nucleotides trimmed from the 5' end of read 2 and the number of poly-A nucleotides trimmed from the 3' end. The trimmed bases are present in the sequence of the BAM record, and the CIGAR string shows the position of these soft-clipped sequences.

</LinkableSection>

<LinkableSection id={"ff-aligner"} nested={true} title={"Transcript alignment for Fresh Frozen tissues"}>

For fresh-frozen tissues Space Ranger uses [STAR](https://github.com/alexdobin/STAR) to perform splicing-aware alignment of transcript reads to the genome. This is the default algorithm unless the `--probe-set` option is invoked for FFPE tissues, [see below](#probe-aligner). After alignment, Space Ranger uses the transcript annotation GTF file to count each read as either exonic, intronic, or intergenic. Space Ranger counts a read as exonic if at least 50% of it intersects an exon, and as intronic if > 50% of its bases map to a gene but not to one of that gene’s exons. Otherwise, the read is counted as intergenic. For reads that align to a single exonic locus, but also align to one or more non-exonic loci, the exonic locus is prioritized and the read is considered to be confidently mapped to the exonic locus with mapping quality (MAPQ) of 255. All uniquely mapping reads have a MAPQ of 255. For multi-mapping reads, the MAPQ score is defined as

$MAPQ=int(-10*log_{10}(1-\frac{1}{N_{map}}))$

where ${N_{map}}$ is the number of loci a read can map to. BAM tag `NH:i` gives the value of ${N_{map}}$ which is 1 for uniquely mapped reads and > 1 for multi mapped reads.

Space Ranger further aligns exonic reads to annotated transcripts, looking for compatibility. A read that has bases 100% compatible with the exons of an annotated transcript, and aligned to the same strand, is considered mapped to the transcriptome. Space Ranger ignores antisense reads that are defined as any read with alignments to an entire gene on the opposite strand and no sense alignments. If the read is compatible with a single gene annotation, it is considered uniquely (confidently) mapped to the transcriptome. These confidently mapped reads are the only ones considered for UMI counting.

<DocumentCallout>
<Text as={"span"}>In the web_summary.html, the set of reads carried forward to UMI counting is referred to as Reads mapped confidently to transcriptome.</Text>
</DocumentCallout>

</LinkableSection>

<LinkableSection id={"probe-aligner"} nested={true} title={"Probe alignment for FFPE tissues"}>

Space Ranger 1.3 introduces support for formalin fixed paraffin embedded (FFPE) tissues. During the FFPE workflow, whole transcriptome probe panels, consisting of a pair of probes for each targeted gene, are added to the tissue. These probe pairs hybridize to their target transcript and are then ligated together.

To analyze FFPE data it is necessary to use the `--probe-set` option to specify a probe set reference CSV file. When this option is invoked, Space Ranger will count ligation events using the probe aligner algorithm. Reads are also aligned to the reference transcriptome using STAR, but only to determine their alignment positions and CIGAR strings; STAR alignments are not used to assign reads to genes for FFPE data. Sequencing reads are aligned to the probe set reference and assigned to the genes they target. The probe alignment algorithm is similar to a seed-and-extend aligner, where each half of the read is a seed, and is described in detail below.

1. Build an index of the half-probe sequences in the probe set reference CSV.
2. For each read, look up each read half in this index, allowing up to one mismatch and no indels.
3. If both halves of the read map to the same probe ID, the read is confidently mapped with a MAPQ (mapping quality) of 255. Only reads with a mapping quality value of 255 contribute to UMI counts.
4. If one half maps and the other half does not map, compare the sequence of the unmapped half to the expected sequence for that probe, allowing mismatches but not indels. If it matches exceeding the minimum alignment score (30, scoring +1 for a match and -1 for a mismatch), the read is confidently mapped.
5. If the unmapped half of the read does not match the expected sequence for that probe, the read is half-mapped with a MAPQ of 1, and does not contribute to UMI counts.
6. If both halves of the probe map but to different probes, the read is ambiguously mapped with a MAPQ of 3, and does not contribute to UMI counts.
7. If neither probe half aligns to the probe set reference by the probe aligner algorithm, the read is unmapped and will have MAPQ=0 (column 5). If neither probe half aligns to the probe set reference by the probe aligner algorithm and the reference transcriptome by STAR, the read will be UNMAPPED (0x4) in FLAG (column 2) and also have MAPQ=0.
8. All reads with up to three mismatches are guaranteed to align.

<Image src={"https://cdn.10xgenomics.com/image/upload/v1655141151/software-support/Spatial-GEX/SR-v2.0/FFPEMappingMetrics.png"} />

<br />

The BAM tag `pr:Z` reports a semicolon-separated list of probe IDs. See BAM Alignment Tags for a detailed description.

</LinkableSection>

<LinkableSection id={"probe-filter"} nested={true} title={"Probe filtering for FFPE tissues"}>

The probe reference is filtered to remove genes/features where one or more of the probes targeting this feature might hybridize and ligate at non-targeted loci. Probes that are predicted to have off-target activity to homologous genes or sequences are excluded from analysis by default. These probes are marked with `FALSE` in the `included` column of the probe set reference CSV. Any gene that has at least one probe with predicted off-target activity will be excluded from filtered outputs. Setting the `--filter-probes=true` command line argument of `spaceranger count` will result in UMI counts from all non-deprecated probes, including those with predicted off-target activity, to be used in the analysis. Probes whose ID is prefixed with `DEPRECATED` are always excluded from the analysis.

</LinkableSection>

<LinkableSection id={"10x-barcode"} nested={true} title={"10x Barcode correction"}>

To determine whether barcode sequence is correct, Space Ranger compares 10x Barcodes to the known barcodes for a given assay chemistry, which are stored in a [barcode whitelist file](https://kb.10xgenomics.com/hc/en-us/articles/360041426992-Where-can-I-find-the-Space-Ranger-barcode-whitelist-and-their-coordinates-on-the-slide-). For example, there are 4992 barcodes in the whitelist for Visium slides with 6.5 mm Capture Area and 14336 barcodes for Visium slides with 11 mm Capture Area.

Space Ranger uses the following algorithm to correct putative barcode sequences against the whitelist:

1. Count the observed frequency of every barcode on the whitelist in the dataset.
2. For every observed barcode in the dataset that is not on the whitelist and is at most one Hamming distance away from the whitelist sequences:

- Compute the posterior probability that the observed barcode did originate from the whitelist barcode but has a sequencing error at the differing base (by base quality score).
- The corrected barcodes are used for all downstream analysis and output files.

In the output BAM file, the original uncorrected barcode is encoded in the `CR` tag, and the corrected barcode sequence is encoded in the `CB` tag. Reads that cannot be assigned a corrected barcode will not have a `CB` tag.

</LinkableSection>

<LinkableSection id={"umi-count"} nested={true} title={"UMI counting"}>

Before counting UMIs, Space Ranger attempts to correct for sequencing errors in the UMI sequences. Reads that were confidently mapped to the transcriptome are placed into groups that share the same barcode, UMI, and gene annotation. If two groups of reads have the same barcode and gene, but their UMIs differ by a single base (i.e., are Hamming distance 1 apart), then one of the UMIs was likely introduced by a substitution error in sequencing. In this case, the UMI of the less-supported read group is corrected to the UMI with higher support.

Space Ranger again groups the reads by barcode, UMI (possibly corrected), and gene annotation. If two or more groups of reads have the same barcode and UMI, but different gene annotations, the gene annotation with the most supporting reads is kept for UMI counting, and the other read groups are discarded. In case of a tie for maximal read support, all read groups are discarded, as the gene cannot be confidently assigned.

After these two filtering steps, each observed barcode, UMI, gene/feature combination is recorded as a UMI count in the unfiltered feature-barcode matrix. The number of reads supporting each counted UMI is also recorded in the molecule info file.

</LinkableSection>

<LinkableSection id={"tissue-calling"} title={"Detecting tissue barcodes"}>

Space Ranger detects spots under the tissue section in the Imaging subpipeline. Only the barcodes associated to these under tissue spots are captured in the Filtered feature-barcode matrix and are used for downstream analyses.

</LinkableSection>

<LinkableSection id={"secondary-analysis"} title={"Secondary analysis of gene expression"}>

Space Ranger uses the feature barcode matrix and the spatial location data from the image to generate secondary analysis results including clusters, t-SNE and UMAP projections as well as differential gene expression between the clusters. All of the secondary data are recorded in the `cloupe.cloupe` file which can be visualized in Loupe Browser.

</LinkableSection>

<LinkableSection id={"dim-reduction"} nested={true} title={"Dimensionality reduction"}>

#### PCA

In order to reduce the gene expression matrix to its most important features, Space Ranger uses Principal Components Analysis (PCA) to change the dimensionality of the dataset from (spots x genes) to (spots x _M_) where _M_ is 10. The pipeline uses a python implementation of IRLBA algorithm, (Baglama & Reichel, 2005), which is modified to reduce memory consumption.

#### t-SNE

For visualizing data in 2-d space, Space Ranger passes the PCA-reduced data into t-Stochastic Neighbor Embedding (t-SNE), a nonlinear dimensionality reduction method (Van der Maaten, 2014). The C++ reference implementation by Van der Maaten (2014) was modified to take a PRNG seed for determinism. The runtime is also decreased by fixing the number of output dimensions at compile time to two or three. The t-SNE is visualized in both `web_summary.html` and in Loupe Browser.

#### UMAP

Space Ranger also supports Uniform Manifold Approximation and Projection (UMAP), which estimates a topology of the high dimensional data and uses this information to estimate a low dimensional embedding that preserves relationships between datapoints (McInnes & Healy, 2018). The pipeline uses the python implementation of this algorithm by McInnes & Healy (2018). UMAP coordinates are available in the pipeline output, but not displayed in the `web_summary.html` and in Loupe Browser.

</LinkableSection>

<LinkableSection id={"clustering"} nested={true} title={"Clustering"}>

Space Ranger uses two different methods for clustering spots by expression similarity, both of which operate in the PCA representation.

#### Graph-based

The graph-based clustering algorithm consists of building a sparse nearest-neighbor graph (where spots are linked if they are among the _k_ nearest Euclidean neighbors of one another), followed by Louvain Modularity Optimization (LMO; Blondel, Guillaume, Lambiotte, & Lefebvre, 2008), an algorithm which seeks to find highly-connected "modules" in the graph. The value of _k_, the number of nearest neighbors, is set to scale logarithmically with the number of spots. An additional cluster-merging step is done: Perform hierarchical clustering on the cluster-medoids in PCA space and merge pairs of sibling clusters if there are no genes differentially expressed between them (with B-H adjusted p-value below 0.05). The hierarchical clustering and merging is repeated until there are no more cluster-pairs to merge.

The use of LMO to cluster spots was inspired by a similar method in the R package [Seurat](http://satijalab.org/seurat).

#### K-means clustering

Space Ranger also performs traditional K-means clustering across a range of _K_ values, where _K_ is the preset number of clusters.

</LinkableSection>

<LinkableSection id={"dge"} nested={true} title={"Differential expression"}>

In order to identify genes whose expression is specific to each cluster, Space Ranger tests, for each gene and each cluster, whether the in-cluster mean differs from the out-of-cluster mean.

In order to find differentially expressed genes between groups of spots, Space Ranger uses the quick and simple method sSeq (Yu, Huber, & Vitek, 2013), which employs a negative binomial exact test. When the counts become large, Space Ranger switches to the fast asymptotic beta test used in edgeR (Robinson & Smyth, 2007). For each cluster, the algorithm is run on that cluster versus all other spots, yielding a list of genes that are differentially expressed in that cluster relative to the rest of the sample.

Space Ranger's implementation differs slightly from that in the paper. In the sSeq paper, the authors recommend using DESeq's geometric mean-based definition of library size (Love, Huber & Anders, 2014). Space Ranger instead computes relative library size as the total UMI counts for each spot divided by the median UMI counts per spot. As with sSeq, normalization is implicit in that the per-spot library-size parameter is incorporated as a factor in the exact-test probability calculations.

</LinkableSection>

<LinkableSection id={"spatial-enrichment"} nested={true} title={"Spatial enrichment"}>

Space Ranger quantifies spatial enrichment, measured by Moran's I, as a discovery tool that can be useful to identify features that have distinct patterns of expression (spatial autocorrelation). Moran’s I is not related to differential expression as it is independent from any clustering information. Features with similar Moran's I do not necessarily have similar spatial expression patterns although methods do exist for identifying groups of genes with similar spatial enrichment patterns. The Moran's I metric scale ranges from -1 (perfectly dispersed) to 1 (perfectly enriched).

</LinkableSection>

<LinkableSection id={"lda-based-spot-deconvolution-7e5466"} title={"LDA-based spot deconvolution"}>

Space Ranger v2.1 and later supports reference-free spot deconvolution on every sample that contains a gene expression library.

The algorithm is built on Latent Dirichlet Allocation (LDA) and is similar to to STdeconvolve (Miller et al. 2022). Given an initial _K_ = _N_ graph-based clusters + 2, LDA is performed using all gene-expression features with at least 10 UMIs in the sample and spots with at least 100 features detected. Each spot is assigned an estimated proportion from _K_ topics, thought of as cell types or cell type mixtures, which add to 1. Next, hierarchical clustering is performed using average linkage and Manhattan distance. For each _K_ topics until K = 2 is reached, similar branches are collapsed and the sum is taken between each collapsed pair. This allows the user to explore different numbers of topics dependending on a priori knowledge of cell types in their sample and the granularity of cell types they want to deconvolve spots to. Dendrograms named `dendrogram_k{N}.png` and `dendrogram_k{N}_distances.png` show how each K-1 is collapsed and the distance between topics, respectively. For each _K_, `deconvolution_topic_features_k{N}.csv` `deconvolved_spots_k{N}.csv` are produced. `deconvolution_topic_features_k{N}.csv` contains a pseudocount of that feature in each topic as well as a log2 fold change calculation between all other topics. This file can be used like a differential expression table to annotate each topic. `deconvolved_spots_k{N}.csv` shows the proportion of each topic within each spot, representing the estimated mixture of cells within a spot. Space Ranger and Loupe have also streamlined the process of picking the number of topics and annotating topics by designing a GUI-based workflow.

</LinkableSection>

<LinkableSection id={"protein-expression-519f8d"} title={"Protein Expression"}>

Because of the inherent technical background common to antibody-based assays, 10x Genomics uses isotype controls to normalize the counts of antibody data. For each protein feature in each barcode the UMI counts are divided by 1 + the sum of isotype control UMI counts. These counts are next multiplied by a scale factor of 10,000 and floored to be an integer. These isotype normalized counts are contained within the `filtered_feature_bc_matrix.h5` and the `filtered_feature_bc_matrix/matrix.mtx.gz` files and are what is shown in the Loupe browser for all isotype-normalized protein data.
The raw feature-barcode matrices contain the raw antibody UMI counts for each barcode. The `isotype_normalization_factors.csv` can be multipled with raw counts to obtain the isotype-normalized counts in the filtered feature-barcode matrices.

</LinkableSection>

<LinkableSection id={"references"} title={"References"}>

Baglama, J. & Reichel, L., Augmented Implicitly Restarted Lanczos Bidiagonalization Methods. SIAM Journal on Scientific Computing 27, 19–42 (2005).

Blondel, V. D., Guillaume, J.-L., Lambiotte, R. & Lefebvre, E. Fast unfolding of communities in large networks. Journal of Statistical Mechanics: Theory and Experiment 2008, (2008).

Love, M. L., Huber, W. & Anders, S., Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2. Genome Biology 15, number 550 (2014).

McInnes, L, Healy, J, UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction. [arXiv (2018)](https://arxiv.org/abs/1802.03426).

Miller, B.F., Huang, F., Atta, L. et al. Reference-free cell type deconvolution of multi-cellular pixel-resolution spatially resolved transcriptomics data. Nat Commun 13, 2339 (2022).

Robinson, M. D. & Smyth, G. K. Small-sample estimation of negative binomial dispersion, with applications to SAGE data. Biostatistics 9, 321–332 (2007).

Van der Maaten, L., Accelerating t-SNE using Tree-Based Algorithms. Journal of Machine Learning Research 15, 3221-3245 (2014).

Yu, D., Huber, W. & Vitek, O., Shrinkage estimation of dispersion in Negative Binomial models for RNA-seq experiments with small sample size. Bioinformatics 29, 1275–1282 (2013).

</LinkableSection>


GEX Algorithms 

Key read processing steps for genome and transcriptome alignment

Space Ranger Algorithms Overview: Gene and Protein Expression 


<LinkableSection id={"overview"} title={"Overview"}>

Space Ranger relies on image processing algorithms to solve two key problems with respect to the slide image: deciding where tissue has been placed and aligning the printed fiducial spot pattern. Tissue detection is needed to identify which capture spots, and therefore which barcodes, will be used for analysis. Fiducial alignment is needed so Space Ranger can know where in the image an individual barcoded spot resides, since each user may set a slightly different field of view when imaging the Visium capture area.

These problems are made difficult by the fact that the image scale and size are unknown, an unknown subset of the fiducial frame may be covered by tissue or debris, each tissue has its own unique appearance, and the image exposure may vary from run to run.

If either of the procedures described here fail to perform adequately, the user can use the manual alignment and tissue selection wizard in Loupe Browser. In most cases, the pipeline is not able to indicate that a failure has occurred and the user is encouraged to check the quality-control image in the **Summary** tab of the Web Summary that Space Ranger outputs. Note that the user supplied full resolution original image is used for downstream visualization in Loupe Browser.

Finally, Space Ranger v2.0 onwards the automatic image analysis described here, will have <code>--reorient-images=true</code> by default which will automatically rotate and mirror the image such that the "hourglass" fiducial is in the upper-left (see details in Fiducial alignment):

| **Properly Oriented Slide Image**                                                                                                      | **Corner with Hourglass Fiducial**                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Image src={"https://cdn.10xgenomics.com/image/upload/v1679090576/software-support/Spatial-GEX/Sustaining/tissue_lowres_image.png"} /> | <Image src={"https://cdn.10xgenomics.com/image/upload/v1679090564/software-support/Spatial-GEX/Sustaining/hourglass_fiducial.png"} width={"535px"} /> |

</LinkableSection>

<LinkableSection id={"fiducial-alignment"} title={"Fiducial alignment"}>

Visium contains a system for identifying the slide-specific pattern of invisible capture spots printed on each slide and how these relate to the visible fiducial spots that form a frame around each capture area. The fiducial frame has unique corners and sides that the software attempts to identify.

This process first extracts features that "look" like fiducial spots and then attempts to align these candidate fiducial spots to the known fiducial spot pattern. The spots extracted from the image will necessarily contain some misses, for instance in places where the fiducial spots were covered by tissue, and some false positives, such as where debris on the slide or tissue features may look like fiducial spots.

After extraction of putative fiducial spots from the image, this pattern is aligned to the known fiducial spot pattern in a manner that is robust to a reasonable number of false positives and false negatives. The output of this process is a coordinate transform that relates the Visium barcoded spot pattern to the user's tissue image.

From Space Ranger v2.0 onwards the pipeline is run with the flag <code>--reorient-images=true</code> by default which removes the constraint of the hourglass fiducial marker needing to be in the upper-left corner. This is accomplished by running the alignment algorithm against each of the eight possible fiducial frame transformations (all rotations by 90 degrees plus mirroring) and choosing among those the
alignment with the best fit.

</LinkableSection>

<LinkableSection id={"tissue-detection"} title={"Tissue Detection"}>

Each area in the standard Visium slide contains a grid of 4,992 capture spots and 14,336 capture spots in the XL Visium slide, all of which are populated with spatially barcoded probes for capturing poly-adenylated mRNA. In practice, only a fraction of these spots are covered by tissue. In order to restrict Space Ranger's analysis to only those spots where tissue was placed, Space Ranger uses an algorithm to identify tissue in the input brightfield image.

Using a grayscale, downsampled version of the input image while maintaining the original aspect ratio, multiple estimates of tissue section placement are calculated and compared. These estimates are used to train a statistical classifier to label each pixel within the capture area as either tissue or background.

The quality control image below shows the result of this process. Individual image pixels determined to be tissue are colored red. The locations of the invisible capture spots are drawn as gray circles when over background.

| **Quality Control Image**                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <Image src= {"https://cdn.10xgenomics.com/image/upload/v1679090545/software-support/Spatial-GEX/Sustaining/detected_tissue_image_1.2.jpg"} width={"400px"} length={"400px"} /> |

In order to achieve optimal results, the algorithm expects an image with a smooth, bright background and darker tissue with a complex structure. If the area drawn in red does not coincide with the tissue, you can perform manual alignment and tissue selection in Loupe Browser before running Space Ranger. See the Imaging Technical Note for information about how to optimize imaging conditions for automated alignment and tissue detection.

</LinkableSection>

<LinkableSection id={"image-registration"} title={"Image Registration"}>

Support for CytAssist enabled Gene Expression analysis was introduced in Space Ranger v2.0. This workflow includes the use of CytAssist image which has the fiducial frame and optionally, a microscope image (brightfield or fluorescence image types) of the same tissue section on the standard glass slide. When the two image inputs are provided, the images need to be registered for downstream visualization.

The targeted transformation of the image registration process is the 2D similarity transformation, which includes homogeneous scaling, translation, rotation, and mirroring. To enable automated tissue image registration between the microscope image and CytAssist image, the algorithm first estimates the proper scaling and translation so the two tissue sections in the images can be roughly overlaid together. Since the correct rotation and mirroring are hard to estimate, the pipeline addresses this by testing eight possible transformations (all rotations by 90 degrees plus mirroring). The estimated scaling, translation, and rotation are used as the initialization to start the registration which is an optimization process. The optimization relies on the <Anchor href={"https://itk.org/Doxygen/html/classitk_1_1MattesMutualInformationImageToImageMetric.html"} target={"\_blank"}>mutual information metric</Anchor> from the open source software <Anchor href={"https://itk.org"} target={"\_blank"}>ITK</Anchor>. When optimization of all different initializations are complete, the pipeline chooses the best combination based on the smallest metric (entropy) of Mattes mutual information to output as the final registration results.

The resulting quality control image below captures the results of the image registration represented as a checkerboard pattern in which the alternating squares represent the two different image inputs.

<Image src={"https://cdn.10xgenomics.com/image/upload/v1657425260/software-support/Spatial-GEX/SR-v2.0/aligned_tissue_img.jpg"} width={"450px"} length={"450px"} />

</LinkableSection>

<LinkableSection id={"fluorescence-intensity"} title={"Fluorescence intensity"}>

From Space Ranger 2.0 onwards fluorescence intensity in the image at every barcoded-spot location is quantified and is captured in the <code>barcode_fluorescence_intensity.csv</code> file. Each page of an input grayscale image is downsampled to the same dimensions as the <code>tissue_hires_image.png</code> image that can be found in the `outs/spatial` directory. From there the pixels are assigned to each barcoded-spot for each page. The location and size of each spot is defined in <code>tissue_positions.csv</code> and <code>scalefactors_json.json</code>. Space Ranger then calculates the mean and standard deviation of the intensities from pixels that are entirely within the area of the known barcoded-spot location for each page.

</LinkableSection>


Imaging

Use image processing algorithms to solve issues with respect to the slide image

Space Ranger Image Processing Algorithms


<DocumentCallout>
<Text as={"span"}>After June 30, 2023, new Space Ranger releases will no longer support Targeted Gene Expression analysis.</Text>
</DocumentCallout>

<LinkableSection id={"targeted-subsampling"} title={"Targeted subsampling"}>

For Targeted Spatial Gene Expression, subsampling is performed after barcode assignment and prior to alignment. This subsampling is enabled only for sequencing libraries with high depth, exceeding 15,000 reads under tissue per spot, in which spurious molecules can be observed in a small fraction of reads. The desired depth limit can be specified using the argument `--rps-limit=N` or disabled using `--rps-limit=0`, although this is not recommended. The unanalyzed reads are present in the BAM file, unmapped and indicated using the `xf:i:32` tag.

</LinkableSection>

<LinkableSection id={"bait-design"} title={"Design of bait sequences for Targeted Spatial Gene Expression"}>

</LinkableSection>

<LinkableSection id={"overview"} nested={true} title={"Overview of bait design"}>

In order to specifically recover molecules from targeted genes of interest in gene expression libraries, a set of bait oligonucleotides are designed with sequence complementarity for each gene in a targeted panel. Baits designed for the Targeted Spatial Gene Expression assay are 120 base pair (bp) biotinylated oligonucleotides that are used within a hybridization-capture workflow.

Targeted Spatial Gene Expression baits were designed with the following broad design principles:

- Compatibility: Targeted baits can be applied to a variety of gene expression technologies, including Visium Spatial Gene Expression libraries and both 3’ and 5’ Chromium single cell RNA-seq libraries.
- Comprehensiveness: Baits are designed to cover the full set of annotated transcripts for each gene in the target panel, without designing redundant baits across overlapping transcript sequences. This strategy also confers added robustness by enabling capture of molecules derived from unexpected or poorly-annotated isoforms of target genes.
- Specificity: Baits are chosen to avoid unwanted complementarity to repetitive elements or other problematic genomic sequences that may compromise assay performance.

</LinkableSection>

<LinkableSection id={"transcripts"} nested={true} title={"Which transcripts are targeted?"}>

SBaits are tiled across the full length of all transcripts annotated in the GRCh38-2020-A reference. The transcript annotations in this reference are based on the GENCODE comprehensive set. See release notes for documentation on this new reference.

</LinkableSection>

<LinkableSection id={"tiling"} nested={true} title={"Tiling approach"}>

For each transcript within a gene, bait sequences are designed starting at the 5’ and 3’ ends and progresses inwards until the center of the transcript is reached. Baits are typically 120bp in length (see the [Optimizing Specificity](/support/software/space-ranger/2.1/algorithms-overview/targeted-gex#optimizing-specificity) section for more details on exceptions) and are aimed to tile at 1x coverage. If the transcript length is not a multiple of 120bp, a small coverage gap appears in the center of the transcript (away from the annotated 3’ or 5’ ends). In order to prevent the unnecessary selection of redundant baits from regions of identical sequence shared across transcripts from the same gene, a De Bruijn graph data structure is used. By querying the De Bruijn graph constructed using all 120bp subsequences derived from each transcript, the algorithm ensures that any potential new bait sequence is rejected if it would be redundant with an existing previously-designed bait from the same target gene.

A subtle consequence of this procedure is that the ordering of transcripts can, to some extent, impact the exact set of baits designed for a given gene. We utilize the rankings provided by the [APPRIS database (Annotating principal splice isoforms)](https://ngdc.cncb.ac.cn/databasecommons/database/id/323) to order transcripts such that higher confidence transcript annotations are tiled first. Other measures are taken to make sure ordering is deterministic when ties occur in categorizations from the APPRIS.

</LinkableSection>

<LinkableSection id={"introns"} nested={true} title={"Introns"}>

Introns are not included in our tiling of annotated transcripts, only UTRs and coding regions. As a consequence, intronic reads from targeted genes will be mostly depleted in Targeted Spatial Gene Expression libraries.

</LinkableSection>

<LinkableSection id={"optimizing-specificity"} nested={true} title={"Optimizing specificity"}>

There are many repetitive elements in the transcriptome that, if overlapped by baits, could result in reduced enrichment in Targeted Spatial Gene Expression libraries, particularly within large target gene panels. Before designing baits, _K_-mers with many near-identical occurrences in the genome are identified so that they can be avoided during bait design.

If a bait intended to be designed at a given position contains one of the _K_-mers above, a combination of shifting the bait position up or downstream and removing portions of the bait sequence is used to attempt to retain a functional bait that will not overlap the problematic sequence. If this is not possible, the algorithm will not design a bait at this location.

Approximately 2-3% of baits within the pre-designed panels are shorter than 120bp because of the procedure above.

</LinkableSection>

<LinkableSection id={"bait-custom"} nested={true} title={"Bait designs for custom sequences"}>

Via the [10x Genomics Custom Panel Designer](https://cloud.10xgenomics.com/xenium-panel-designer) users can also design baits for entirely custom exogenous sequences. These sequences follow the same design procedure as endogenous genes, including the procedure described in the [Optimizing Specificity](/support/software/space-ranger/2.1/algorithms-overview/targeted-gex#optimizing-specificity) section. Each custom sequence is treated independently. No check for redundancy is performed between submitted sequences, as would normally occur for transcripts within the same gene. Similarly, no check for further homology between submitted sequences and endogenous sequences is performed.

</LinkableSection>

<LinkableSection id={"mappability-warning-explanation"} nested={true} title={"Identifying genes with low mappability or low bait coverage"}>

In order to assign a UMI to a particular gene, Space Ranger has to be able to confidently identify which gene a given read came from. A small number of genes share a substantial proportion of their sequence content with other genes in the genome, which in extreme cases makes it difficult to assign the corresponding UMI count to a single gene. These genes may have reduced counts in the resulting expression matrices.

The bait design algorithm intentionally avoids designing baits that overlap repetitive sequences as described in the [Optimizing Specificity](/support/software/space-ranger/2.1/algorithms-overview/targeted-gex#optimizing-specificity) section above. A very small number of genes have low coverage of baits around annotated transcript ends due to the presence of repetitive sequences. These genes are flagged with poor coverage within the last 360bp of the 3’ or 5’ ends of annotated transcripts, where the majority of signal for most genes is expected to be localized in 3'/5' gene expression libraries. While the baits that are provided for these genes may work well, enrichment of these genes may be less robust depending on the particular sample and location of library molecules within annotated transcripts.

Genes with very low mappability or low bait coverage at annotated transcript ends are noted using the `mappability_flag` column in the gene metadata file provided for predesigned and customized panels. These genes will also trigger a warning if added to customized panels via the [10x Genomics Custom Panel Designer](https://cloud.10xgenomics.com/xenium-panel-designer).

</LinkableSection>

<LinkableSection id={"reviewing-mappability-warnings"} nested={true} title={"Reviewing genes with mappability warnings"}>

If a gene you want to add to your panel has triggered a mappability warning (or equivalently has the value `TRUE` in the `mappability_flag` column of the gene metadata file), the following steps are recommended:

1. Check if this gene has near-zero counts in existing whole transcriptome datasets. If so, this warning may indicate the gene is very poorly mappable and Space Ranger is not able to assign many reads to this gene. Targeting this gene may not yield the desired results.
2. If you have existing whole transcriptome data, you can use IGV or another genome browser to view coverage within this gene alongside the bait locations (as defined in the panel's BED12 file). If the baits appear to cover the regions where reads have aligned, then enrichment is likely to work well. If baits do not overlap the main regions of coverage, enrichment may not work well for this gene and you may want to consider whether to include this gene on your panel. See our documentation on BED12 files for more information.

</LinkableSection>

<LinkableSection id={"gene-enrichment"} title={"Modeling Targeted Spatial Gene Enrichments (count)"}>

In a Targeted Spatial Gene Expression sample, it is assumed that there are two classes of genes: genes from the target panel that are enriched by targeting, and non-targeted genes that constitute the background. Since the number of reads per gene in the sample before targeting is not known, standard approaches to directly calculate read enrichments are not available. Instead, the mean number of reads per UMI (or Mean Reads per UMI) for each gene is calculated, which serves as a proxy for read enrichment. The mean number of reads per UMI for a gene is closely related to the sequencing saturation for that gene ($mean\;reads\;per\;UMI=\frac{1}{1 - sequencing\;saturation}$), also see Metrics.

Given there are a finite number of UMIs per gene in a given sample, enrichment will tend to recover more UMIs from those genes as well as more PCR duplicates arising from those UMIs. Therefore enriched genes are likely to have greater sequencing saturation and greater mean reads per UMI.

In order to assess whether targeted genes were enriched in a given sample, the mean reads per UMI values are first calculated for all genes (both targeted and non-targeted genes). Only UMIs in tissue-associated barcodes are used and only genes with at least 10 UMIs in tissue-associated barcodes are considered for this analysis. Space Ranger then fits a two-component Gaussian Mixture Model to the mean reads per UMI distribution, grouping genes into one of two classes: enriched genes (those with higher mean reads per UMI) and non-enriched genes (those with lower mean reads per UMI). The numbers of targeted and non-targeted genes that are considered enriched by this method are shown in the Targeted Spatial Gene Expression Run Summary] Targeted Enrichment dashboard.

Space Ranger may sometimes be unable to confidently assign genes as enriched or non-enriched using this method, particularly when there are too few targeted and/or non-targeted genes meeting the criteria above, or if sequencing saturation is too low. In these rare cases, enrichment calculations may be disabled, and the metrics reporting the number of genes enriched will be `N/A`.

</LinkableSection>

<LinkableSection id={"gene-enrichment-compare"} title={"Modeling Targeted Spatial Gene Enrichments (targeted-compare)"}>

The computation of gene enrichments in targeted-compare is analogous to that described above, with one modification. When running targeted-compare, the parent sample read counts are known, allowing for direct calculation of read enrichments. Space Ranger therefore uses the same Gaussian Mixture Model described above, substituting Mean Reads per UMI with Read Enrichments. Read Enrichments per Gene are calculated as (Number of reads in the Targeted Sample)/(Number of reads in the Parent Sample), after rescaling both samples to the same number of read pairs from Gene Expression libraries.

</LinkableSection>


Targeted Algorithms 

Learn more about the Targeted Spatial GEX algorithm

Space Ranger Targeted Gene Expression Algorithms Overview

10x Genomics Visium Spatial Software Suite

Overview

Getting Started

Download Center

Analysis

Tutorials

Algorithms

Advanced

Release Notes

Datasets

Loupe Browser

Space Ranger 2.1

Space Ranger

Install Space Ranger and perform a test run

Set up Space Ranger

Learn how to analyze fresh frozen (FF) samples with spaceranger count

Running spaceranger count (FF)

Space Ranger for FF

Learn how to analyze formalin fixed paraffin embedded (FFPE) samples with spaceranger count

Running spaceranger count (FFPE)

Space Ranger for FFPE

Learn how to analyze tissue microarray (TMA) samples with spaceranger count

Analyzing CytAssist Tissue Microarray Data with spaceranger count

Space Ranger for CytAssist TMA

Learn how to use protein expression to filter and visualize your data

Protein Expression Visualization and Thresholding with Loupe Browser

Protein Expression and Thresholding

Learn how to perform reference-free spot deconvolution using a public mouse brain dataset

Spot Deconvolution

View all tutorials

Learn about input files required to run Space Ranger

Inputs

Generating FASTQs

Specifying FASTQs

Demultiplexing with Illumina software

Image recommendation

Slide parameters

Slide layout download

Manual fiducial alignment

Manual CytAssist image alignment

Running Pipelines

Choosing a pipeline

Computing options

Space Ranger commands

Troubleshooting

count (Spatial GEX)

count (CytAssist GEX)

count (CytAssist GEX + PEX)

Feature Reference

Aggr

Learn about the output files generated by Space Ranger

Outputs

Web Summary

Secondary Analysis

Matrices

Spatial Outputs

Spot Deconvolution Outputs

Molecule Info (H5)

Count Outputs

Aggr Outputs

Space Ranger is a set of analysis pipelines that process Visium data with brightfield and fluorescence microscope images. Space Ranger allows users to map the whole transcriptome in formalin fixed paraffin embedded (FFPE) and fresh frozen (FF) tissues.

What is Space Ranger?

We provide resources from protocols, user guides, and free-to-use analysis tools.

Algorithms overview

Advanced pipeline content for Space Ranger.

Browse Q&As from the 10x Genomics support team.

Access free public Visium data from 10x Genomics.

A collection of introductions, tutorials, and blogs for data analysis beyond software.

Analysis Guides

Loupe Browser is a desktop application that allows you to interactively visualize data.