New features & improvements

• Automatically corrects Visium HD CytAssist images generated with instrument firmware v2.1 to account for a bug that affects registration between gene expression data and the microscope image.
• Adds metrics "Number of UMIs per mm squared of Tissue" and "Number of Reads per mm squared of Tissue" to the web_summary.html file.

Bug fix

• Resolved an issue where the Space Ranger count pipeline could fail unexpectedly during spot deconvolution for Visium v1 and v2 samples.

Bug fix

• In Space Ranger v3.1.0, the web_summary.html file erroneously shows a warning message about tissue registration performance for all analyses that include Visium HD data and a microscope image, even when metrics indicate that automated tissue registration did not have an issue. This bug is resolved in Space Ranger v3.1.1.

New features & improvements

• The pipeline has been overhauled to significantly improve the CytAssist to microscope image registration process. For more information about CytAssist image to microscope image registration, please visit the image processing algorithms page.
• The web_summary.html file has been optimized to reduce the file size. This size reduction ensures that the web summary is less than 20 MB and that it is below the attachment file size limit set by most email providers.
• Space Ranger now supports custom bin sizes of 4 µm and 6 µm in the --custom-bin-size argument for Visium HD datasets. A Loupe file (.cloupe) will only be generated if the custom bin size is larger than 8 µm.
• The web_summary.html file now includes the CytAssist run name, instrument serial number, and instrument firmware version when a CytAssist image is provided as an input into spaceranger count.
• The web_summary.html file displays a warning message when image registration metrics indicate potential issues with image registration.
• The Space Ranger automated tissue detection algorithm has been updated for Visium v1 and Visium v2 in order to improve performance for tissues that cover the entire capture area. For a Visium v1 or v2 dataset run with Space Ranger v3.1, users may encounter some differences in tissue detection when compared to the same dataset run with v3.0 or older.
• Visium HD barcode extraction parameters have been updated, resulting in 0.5-1% more reads with valid detected barcodes. For a Visium HD dataset run with Space Ranger v3.1, users can therefore expect slight increases in genes, UMIs, and other downstream metrics when compared to the same dataset run with v3.0.

Bug fixes

• If users attempt to aggregate Visium HD datasets, spaceranger aggr now provides an error message that this is not currently supported.

Bug fixes

• Fixed a bug in the web summary file on the Total UMI Count to Image Alignment chart where the top end of the scale was determined based on the 98th percentile of UMI counts under all bins rather than bins under tissue.
• Fixed a bug where references containing genes without transcripts led to the incorrect selection of genes in the filtered feature-barcode matrix.
• Fixed a bug that occured when running HD with the --no-secondary option. The feature slice H5 now contains masks for the 8 µm and 16 µm bins as expected.

Other updates

• Space Ranger help text has been updated to clarify pipeline behavior which was unclear in the previous release:
  • The --image, --darkimage and --colorimage flags are optional if user provides --cytaimage
  • The --slide and --area flags are optional if the Space Ranger can retrieve the information from the CytAssist image metadata (requires that the image was generated on CytAssist with instrument FW v1.2 or higher)
  • The --unknown-slide option is strongly recommended against for HD
• Some error messages have been updated for clarity.
• If users create a pipestance where the CytAssist image metadata is inaccurate and the user sets an accurate slide serial number value via --slide, and also includes --override-id, the pipeline runs to completion based on the --slide argument.

New feature: Visium HD Spatial Gene Expression

• Space Ranger v3.0 now supports Visium HD Spatial Gene Expression (“Visium HD”).
• New slides that enable single cell scale (continuous 6.5 mm grid of 2 x 2 µm barcoded squares with no gaps).
• Reads are binned into 8 x 8 µm squares to improve data quality while maintaining single cell-scale resolution.
• Users can analyze raw data (2 x 2 µm resolution) or set custom bin sizes (10-100 µm, even numbers only).
• Entering the correct slide serial number and capture area are important for the best quality data. These metadata are also captured in the CytAssist image. Entering an incorrect serial number and/or capture area may result in unusable data.
• Loupe Browser v8.0 is required to work with .cloupe files output by Space Ranger v3.0.

Downloads

• The slide layout download form has moved to the Download Center (only required for when Space Ranger is not connected to the internet).
• The new v2 mouse probeset is available for download.

Getting started

• The Getting Started sections, including the Glossary and What is Space Ranger pages, have been overhauled to make it easy for new users to navigate analysis options and run Space Ranger on their chosen Visium data type.

Inputs

• CytAssist image for Visium HD must be run with firmware v2.0 or later. New manual alignment tutorial for Visium HD that is distinct from v1/v2 workflows.
• Visium HD slide ID detection is automated through the CytAssist image metadata.
• Slide parameters page has been updated with HD slide information.

Running pipelines

• New page on how to run Visium HD data with spaceranger count.
• Users must choose whether or not to generate a bam with the --create-bam argument.
• Users can set the --image-scale option to get more robust alignments in the spaceranger count pipeline.
• An updated list of command line options can be found here.
• Visium HD analysis is not supported in spaceranger aggr.

Outputs

• The Visium HD web summary is structured to surface the most important quality control metrics to assess your data for downstream analysis.
• The directory structure of the outs has been modified to accommodate binning. A full set of outputs is only provided for the 8 µm bin size by default. Raw data are also provided at 2 µm resolution. Custom bin sizes are also enabled.
• Filtered and raw matrices are not provided for HD data in the top level outs. Instead, see the binned outputs.
• Tissue_hires_image.png now supports 6,000 pixels on its longest image dimension.
• New files for Visium HD include a tissue positions parquet and hd_feature_slice.h5.
• The barcode fluorescence intensity file is not present for Visium HD.
• t-SNE is disabled for Visium HD.
• Moran's I is not calculated for Visium HD.
• Spot deconvolution is not enabled in Space Ranger for Visium HD.
• Secondary analysis is run on binned data only for Visium HD.

Image processing improvements

• Improved CytAssist to microscope image registration.
• Detection of new Visium HD fiducials.
• Perspective correction of the CytAssist image based on fiducials.
• Improved tissue boundary detection.

Binning

• No secondary analysis on 2 µm square size.
• Algorithms optimized for up to ~700k bins.

Deprecated product

• SR 3.0 does not support spatial targeted gene expression. The library compatibility table in the Getting Started section has been updated to reflect this. Details relevant only to targeted gene expression have been removed from the Space Ranger 3.0 documentation.

Bug fix

• Fixed a bug where 8-bit grayscale images were inadvertently turned into 8-bit RGB color images for tissue registration.
• Added support for NovaSeq X demultiplexing with the bcl2fastq v2.20 dependency.

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

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, 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

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.

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.

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.

Copy
  └── 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.

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.

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.

• 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.

• 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.

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.

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.

• Initial release.