New feature: Gene + Protein Expression on Visium CytAssist:
- Supported in `spaceranger count` and `spaceranger aggr`
- Gene and protein expression counts included in feature-barcode matrices
- Built-in protein expression normalization using isotype controls
- New ``--libraries``, ``--feature-ref``, and ``--no-libraries` options for running Protein Expression libraries
- Comprehensive QC metrics and plots for protein expression in web_summary.html
- New tutorial: [Protein Expression Visualization and Thresholding with Loupe Browser](/support/software/space-ranger/loupe-browser/tutorials/space-ranger-protein-thresholding)

New feature: Reference-free Spot Deconvolution:
- A convenient alternative for when a single cell reference is not available or to look at cell type level spatial data without relying on third-party tools. 
- The algorithm is built on latent Dirichlet allocation, similar to [STdeconvolve](https://www.nature.com/articles/s41467-022-30033-z), and outperforms reference guided spot deconvolution with a poorly matched reference.
- Hierarchically clustered deconvolution results reflect different granularity of cell typing.
- Predicts latent topics that are inferred cell types. Outputs in deconvolution folder can be used to annotate topics with biological cell types.
- Supported for all Gene Expression libraries in `spaceranger count` and `spaceranger aggr`
- New tutorial: [Spot Deconvolution with Space Ranger and Loupe Browser](/support/software/space-ranger/loupe-browser/tutorials/space-ranger-spot-deconvolution)

Other updates:
- Space Ranger 2.1 is the last version that will support Targeted Gene Expression analysis.
- New output for probe-based assays: probe barcode count matrix when running with probe set to see how probes contributed to total gene UMI counts per spot.
- Added support for bigtiff (btf, tf2, and tf8) image file extensions.
- Analysis output filenames prefixed with library type: `gene_expression` and `antibody_capture`.
- Added gene and UMI violin plots in web_summary.html for gene expression tab.
- Minor tweaks to tissue detection algorithm.
- Fixed bug in how gDNA metrics were calculated. Now excludes probes labeled FALSE in the `included` column.

v2.1.0 (May 16, 2023)

Bug fixes and miscellaneous changes:
- Fixed the loading of certain BigTIFF images.
- Fixed the incorrect preflight check error for slide serial number when users use Loupe manual alignment for only CytAssist Image Alignment.
- Web summary usability improvements:
    - Fixed the mapping of the median UMI counts per spot in web_summary.html to the correct metric from metrics_summary.csv.
    - Removed downsampling of spots for spatial and cluster plots to accommodate larger tissue sections on the Visium CytAssist Spatial Gene Expression slides with 11 mm capture area.
    - Updated the display text for reorientation mode in the `web_summary.html` from `rotation+mirror` to `On/Off` for clarity.
    - Fixed a bug in `web_summary.html` when zero reads are mapped.
    - Help text and warning text was updated for clarity.
- Various error messages were updated to be more informative.

v2.0.1 (January 18, 2023):

New feature: CytAssist Spatial Gene Expression:
- Space Ranger now supports CytAssist instrument enabled Gene Expression analysis and expands the image processing sub pipeline to include image registration between the CytAssist image, which contains the tissue section and fiducial frame, and the microscope image (brightfield or fluorescence) of the same tissue section on a standard glass slide.
- The CytAssist generated image is specified using the new option `--cytaimage` in the `spaceranger count` pipeline.
- `spaceranger count` uses the CytAssist generated image to perform automatic fiducial alignment and tissue detection irrespective of the type of microscope image inputs supplied (H&E or immunofluorescence stained tissues). Loupe manual fiducial alignment is optional and not required.
- For image registration using a fluorescence microscope image specified using `--darkimage`, there is a new option `--dapi-index`, which can be used to specify the page index corresponding to a tissue morphology counterstain (e.g., DAPI). When `--dapi-index` is specified, Space Ranger will only use the information from this fluorescence channel to perform automatic image registration.
- New CytAssist Image Alignment QC tool with an interactive opacity slider in the `web_summary.html` to check the image alignment between the CytAssist and microscope image inputs.
- Additional CytAssist-related outputs in the `spatial/` subfolder: `aligned_tissue_image.jpg`, which is useful to check the quality of the image registration  and `cytassist_image.tiff`, which is a copy of the original CytAssist image.

Major updates:
- `spaceranger count` will now quantify fluorescence intensity in the image at every barcoded-spot location. A new output file, `barcode_fluorescence_intensity.csv` is produced that contains measurements from every fluorescence channel and can be combined with feature-spot matrices by matching the barcode sequences.
- Channel names in the column headers of `barcode_fluorescence_intensity.csv` can be set by renaming fluorescence image channels during the manual fiducial alignment workflow in Loupe Browser. The channel names will also persist when opening the `cloupe.cloupe` file in Loupe.
- The `--unknown-slide` flag is now an option that requires users to specify the slide version when the slide serial number is unavailable (e.g., `--unknown-slide=visium-1` for non-CytAssist slides).
- Space Ranger is now compatible with the `QPTIFF` image format.
- CentOS/RedHat >= 7.0 or Ubuntu >= 14.04 is required to run Space Ranger v2.0. Space Ranger v1.3 was the last version that supported CentOS/RedHat 6 or Ubuntu 12.04.
- Visium CytAssist Spatial Gene Expression for FFPE introduces a new and improved Human Transcriptome Probe Set with 3-fold coverage of most genes. The `probe set CSV file` also contains an additional `region` column which indicates whether the probe targets exon-junction-spanning (spliced) or non-exon-junction-spanning (unspliced) regions of the gene.
- New metrics `Estimated UMIs from Genomic DNA` and `Estimated per Probe Background UMI Count` as well as a new `Segmented Linear Model Plot` are added to the **Gene Expression** tab in the web_summary.html when using v2 probe sets that include the `region` column. These metrics provide insight into the level of background noise in the overall UMI counts.
- Images are rotated and mirrored by default to find the optimal fiducial alignment. Users no longer need to specify `--reorient-images` in the `spaceranger count` pipeline when their input image does not have fiducial markers in the correct orientation. `--reorient-images` is now a boolean option instead of a flag so rotation and mirroring can be disabled by setting `--reorient-images=false`.
- Changes have been made to the organization of the `outs/` folder in `spaceranger`.
- For consistency with `cellranger`, secondary analysis outputs are prefixed with the library type.

```
  └── analysis
      └── pca
          └──gene_expression_10_components/
```

- The `spaceranger count` web_summary.html **Analysis** tab has been renamed to **Gene Expression**.
- The BAM and the molecule_info.h5 files now include the slide serial number and the capture area information if provided to the `spaceranger count` run.

Bug fixes and miscellaneous changes:
- Improved error messages and better handling of poorly formatted inputs in `spaceranger mkref`. Enable users to generate references for analyses with large genomes containing chromosomes longer than 512 Mbp. `spaceranger count` pipeline will output a `.csi` BAM index file instead of `.bai` in these cases.
- Updated `spaceranger mkfastq` to autodetect i5 orientation for users who upgraded to Novaseq instrument control software v1.8.
- For `spaceranger count` runs that use a probe set, the value of `Median Genes per Spot` in the `metrics_summary.csv` and web_summary.html is replaced by the `Median Panel Genes per Spot` value from previous versions of `metrics_summary.csv`. `Median Panel Genes per Spot` is now removed from the `metrics_summary.csv`. `Median Genes per Spot` used to include all probes in the probe set and now only includes filtered probes.
- Read 2 length is trimmed to 50 bp by default when a probe set reference CSV is passed using `--probe-set`. User no longer has to set `--r2-length=50` when processing FFPE sequencing libraries.
- The `--no-probe-filter` flag is deprecated and superseded by the boolean option `--filter-probes` with default set to true for filtering probes with off-target activity.
- Added `Visium_Mouse_Transcriptome_Probe_Set_v1.0_mm10-2020-A.csv` and `Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv` to tarball.
- Sequencing quality scores (ie., QV) up to Q93 are now supported. Previously supported up to Q41.
- Fixed bug where pipeline would crash when only 35 spots under tissue were detected. Now pipeline will run to completion, but Moran's I `spatial_enrichment.csv` will not be output when fewer than 37 spots.
- Fixed bug where `spaceranger count` with `--no-bam` flag still generated a BAM file.
- Fixed `software_version` in matrix mtx and h5 headers to reflect the Space Ranger version used to generate the matrices.
- Fixed a bug that resulted in a segmentation fault error when mapping to references that contain small contigs, for example, the rabbit genome.
- Various error messages were updated to be more informative.
- Web summary usability improvements: QC image(s) were moved from the `Spots` panel to a new `Image` panel. Chemistry descriptions were fixed to reflect slide version and assay used. Help text was updated to improve clarity.
- Third-party licensing information added to `THIRD-PARTY-LICENSES.spaceranger.txt` in the tarball.


v2.0.0 (July 18, 2022):

Bug Fixes and Miscellaneous Changes:
- Adds an alert if image alignment would have produced a different result if the `--reorient-images` option was specified.
- Update warning for low fraction of reads confidently mapped to the probe set to be more informative. 
- Unsets additional sysconfig environment variables prior to pipeline execution, which may otherwise interfere with the pipeline conda environment.
- Fixes an issue with mkfastq when bcl2fastq requires `LD_LIBRARY_PATH`.


v1.3.1 (November 1, 2021):

System Requirements:
- The recommended operating systems for Space Ranger 1.3.0 are CentOS 7 or Ubuntu 14 Linux variants or newer. CentOS 6 and Ubuntu 12 are still supported but have been deprecated. Support may be dropped in future versions.

New Feature: Gene Expression from FFPE Samples:
- Gene Expression analysis from formalin fixed paraffin embedded (FFPE) samples is now available in Space Ranger and is invoked by specifying the `--probe-set` option when running the `spaceranger count` command. Space Ranger v1.3.0 or later is required to analyze FFPE data. 
- A new `--no-probe-filter` option can be used to disable the default filtering of certain probes.
- A new probe aligner tailored for use with probe-based assays, such as Visium for FFPE, was developed. When the `--probe-set` option is invoked, Space Ranger aligns reads to the specified probe set to count oligo ligation events. See the algorithms for more details.
- BAM output from probe-based assays includes a new tag `pr:Z` that indicates the probe to which a read aligns and specifies the gene ID, gene name, and a computational hash specific to the probe sequence.
- Visium Spatial Gene Expression for FFPE ships with a new dual index set (Dual Index Kit TS Set A) distinct from the dual index set used for fresh frozen tissues (Dual Index Kit TT Set A). The dual index sets can be detected by `spaceranger mkfastq` based on their abbreviations (e.g., SI-TS-A1) in the sample sheet. Space Ranger v1.3.0 or later is necessary to detect Dual Index Kit TS Set A with `spaceranger mkfastq`.

New Feature: Spatial Autocorrelation (Moran's I):
- Space Ranger now calculates the Moran's I spatial autocorrelation metric on a per-gene basis, highlighting genes with patterns of spatially coherent gene expression for presentation in Loupe Browser and in a new output file `spatial_enrichment.csv`. 

Bug Fixes and Miscellaneous Changes:
- The web summary output from Space Ranger now indicates whether the `--reorient-images` option was specified to enable the automatic rotation of input images.
- The web summary now differentiates probe-based, targeted, and whole genome analyses.
- Space Ranger now uses Python 3 for Python-based stages.
- The `molecule_info.h5` and unfiltered feature-barcode matrix files (raw_feature_bc_matrix in H5 and MEX formats) will only contain barcodes with at least one read, rather than all barcodes in the whitelist.
- A bug that prevented error messages from `spaceranger mkref` from displaying properly when processing GTF files was fixed.
- A bug has been fixed in the graph-based clustering output: previously, in a sample with K clusters, the first K spot-associated barcodes (ordered as in the filtered feature-barcode matrix) may have been assigned incorrect cluster labels. This change does not affect the number of clusters output.
- The `--qc` option has been deprecated from `spaceranger mkfastq`.


v1.3.0 (June 9, 2021):

- Adds support for pyramid TIFFs, or TIFFs with multiple pages of the same image at different resolutions.
- Fixes an issue where targeted samples run against new references would fail preflight.


v1.2.2 (February 3, 2021):

- Fixed an issue in aggr where files would fail to be copied on NFSv4 File Systems.
- Disables multithreading in mkref to address an issue where mkref would fail on hardware without AVX support. This will be fixed in a future release.
- Better error handling if the pipeline fails due to a missing .env.json file due to an incomplete copy of the application folder.

v1.2.1 (December 10, 2020):

New features:
- Targeted Gene Expression analysis is now available in Space Ranger v1.2 and is invoked by specifying the `--target-panel` option when running the `spaceranger count` command.
- Space Ranger 1.2 introduces the new `spaceranger targeted-compare` pipeline for direct comparative analysis of matched parent Whole Transcriptome Amplification (WTA) and Targeted Gene Expression datasets.
- Space Ranger includes the new `spaceranger targeted-depth` subcommand to estimate sequencing depths appropriate for Spatial Targeted Gene Expression experiments based on input WTA results and an associated target panel file.
- A new command line option, `--no-bam`, instructs the pipeline not to construct BAM files.
- The GTF file parsing methods have been changed and some GTF files with non-standard metadata fields may no longer be accepted by Space Ranger. You may need to reformat the metadata fields into a standard layout.
- Performance improvements in reading FASTQ files, writing BAM files, and memory utilization in certain pipeline stages.
- `spaceranger aggr` now outputs a t-SNE projection colored by the input sample.
- Support for Gateway slides containing two standard 6mm capture areas per slide.

Bug Fixes and Miscellaneous Changes:
- The `--unknown-slide` option for `spaceranger testrun` has been renamed `--no-internet` to reflect its intended use.
- Fixed an issue in mkfastq that prevented the `--filter-single-index` option from working correctly.
- Fixed an issue where files would fail to be copied on NFSv4 File Systems.
- The `--nuclei` option was removed from `spaceranger mkref`.
- The colors used in the web summary output to indicate fiducial alignment and tissue detection have been changed to avoid confusion with an H&E stained image.
- The maximum number of colors (channels) in a fluorescence imaging sample has been increased to nine.
- Fixed parsing of some non-standard FASTQ files to avoid errors.
- Bug fixes for GTF files output by mkref:
    - GTF attributes with duplicate keys (e.g., tag "value1"; tag "value2";) are handled correctly. Previously, only the last such attribute was kept.
    - GTF attributes with unquoted integer values (e.g., exon_number 1;) are kept. Previously, they were removed.
    - GTF lines end with semicolons.
    - Unix line endings are used rather than DOS line endings, consistent with other Space Ranger outputs.
    - Fixed problem parsing GTF files with semicolon delimiter inside quotes
- Fixed a numerical stability issue in the PCA method that affected the analysis of some datasets.
- BGI/MGI reads can now be analyzed using Space Ranger.

BAM Output Changes:
- The duplicate flag (0x400) is set correctly in the secondary alignments (flag 0x100) of PCR duplicate reads and low-support UMI reads (xf:i:2)
- Low-support UMI reads (xf:i:2) have the corrected barcode in UB:Z. Previously, it contained the raw barcode.
- The duplicate flag (0x400) is set correctly in the secondary alignments (flag 0x100) of PCR duplicate reads and low-support UMI reads (xf:i:2)
- Low-support UMI reads (xf:i:2) have the corrected barcode in UB:Z. Previously, it contained the raw barcode.
- Reads that are excluded from analysis due to high-depth subsampling in targeted gene expression are unmapped and marked with (`xf:i:32`) in the BAM.

Known Issues:
- The minimum dimension for an input image to Space Ranger is 2000 pixels on a side. Even though the Loupe Manual Aligner may allow smaller images to be used during manual alignment, the pipeline will not process images that are smaller than the minimum.  These limits will be made consistent in an upcoming release.
- Loupe and Space Ranger currently do not support BigTIFF files that contain a multi-resolution image pyramid.  10x is aware that some systems produce such files. The current recommendation is to convert such images externally to a single-resolution image at the highest resolution desired. 

v1.2.0 (October 27, 2020):

New Features:
- Support for fluorescence imaging input such as IHC/IF.
- Aggregation of multiple datasets.
- Optional automatic rotation of slide images.

Runtime Improvements:
- Space Ranger 1.1 runs two to five times faster than Space Ranger 1.0, depending on the sequencing data, and reduces disk I/O by half.

Analysis Improvements:
- The fraction of reads mapped confidently to a gene was improved by up to 9% by trimming template switch oligo (TSO) sequence from the 5' end of read 2 and poly-A from the 3' end prior to alignment.
- Space Ranger now provides consistent sensitivity across a wider range of read lengths, from 70 bp reads to 120 bp reads, enabling use of smaller sequencing kits.
- The recommended references for mouse and human have been updated (new version: 2020-A). The new references remove annotations with weak evidence that prevent alignment to legitimate annotations.

Other Changes:
- Space Ranger 1.1 uses Orbit to perform transcriptome alignment, which leverages a modified STAR v2.7.2a. These modifications provide compatibility with “versionGenome 20201” references, such as those generated by STAR v2.5.1b. In Space Ranger 1.1 we still provide and use STAR v2.5.1b for other purposes such as `spaceranger mkref`. In our testing, we did not note any differences in transcriptome alignments between the STAR shipped in Space Ranger 1.0 (STAR v2.5.1b), STAR v2.7.2a, or Orbit.


v1.1.0

v1.0.0

Release Notes for Space Ranger

10x Genomics Visium Spatial Software Suite

Overview

Getting Started

Download Center

Analysis

Tutorials

Algorithms

Advanced

Release Notes

Datasets

Loupe Browser

Space Ranger

Set up Space Ranger

Learn how to analyze Fresh Frozen samples with spaceranger

Running spaceranger count (FF)

count for FF

Learn how to analyze FFPE samples with spaceranger

Running spaceranger count (FFPE)

count for FFPE

Learn how to analyze tissue microarray samples with spaceranger

Analyzing CytAssist Tissue Microarray Data with spaceranger count

count 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 more about input files required to Space Ranger

Inputs

Generating FASTQs

Specifying FASTQs

Demultiplexing with Illumina software

Image recommendation

Slide parameters

Slide layout download

Fiducial alignment

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 more about the output files generated by Space Ranger

Outputs

Web Summary

Matrices

Spatial Outputs

Spot Deconvolution Outputs

Molecule Info (H5)

Count Outputs

Aggr Outputs

Space Ranger is a set of analysis pipelines that process Visium Spatial Gene Expression 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 tissues to discover novel insights into normal development, disease pathology, and clinical translational research.

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.