Space Ranger's pipelines analyze sequencing data produced from Visium Spatial Gene Expression data. The CytAssist instrument aids in the transfer of ligated probes or antibody tags from the FFPE, FF, or Fixed Frozen (FxF) tissue section on a standard glass slides to the CytAssist Spatial Gene Expression Slide. The workflow diagram shows all the required inputs and the corresponding spaceranger flags for analyzing both Gene Expression (GEX) and Protein Expression (PEX) on CytAssist enabled FFPE, FF, or FxF tissue samples:
The spaceranger count pipeline is run on every individual Capture Area in the Visium slide. The required inputs are:
- The FASTQ files for a given capture area (
--fastqs) - The corresponding CytAssist image in
TIFFwith optional microscope image in eitherTIFF,QPTIFForJPEGformat--cytaimagefor image captured by CytAssist instrument (contains fiducial frame)--imagefor brightfield microscope image--darkimagefor dark background fluorescence microscope image--colorizedimagefor composite colored fluorescence microscope image
- The slide layout GPR file specified by
--slide&--areaifspacerangerhas access to internet--slidefile,--slide&--areaifspacerangerhas no access to internet. The slide layout file is directly downloaded--unknown-slideif visium slide details are unknown
- The reference transcriptome for the species from which the sample was obtained (
--transcriptome) - The probe set reference CSV file specified using
--probe-setflag - The feature reference CSV file specified using
--feature-refflag
For a list of accepted arguments, see the Command Line Argument Reference, or run spaceranger count --help. For analysis of only GEX data, refer to the details on CytAssist Enabled Analysis with spaceranger count page.
The following code examples assume compute platforms are connected to the internet wherespaceranger uses the value of the --slide argument to automatically download the slide layout file in gpr format. In absence of internet connectivity to the compute platform, the user can download the slide specific layout file in gpr format and provide it to spaceranger using the --slidefile argument. Refer to the [Running spaceranger count (FF)] tutorial for detailed walkthrough.
Select the section corresponding to the imaging workflow.
The example code here represents use of a multi channel immunofluorescence microscope image (IF) with one channel stained with DAPI in addition to CytAssist image.
Run spaceranger count with the following arguments. Space Ranger will perform automatic image registration of the two image inputs as well as fiducial alignment and tissue detection on the CytAssist image.
cd /home/jdoe/runs
spaceranger count --id=sample345 \ #Output directory
--transcriptome=/home/jdoe/refdata/GRCh38-2020-A \ #Path to Reference
--probe-set=/home/jdoe/spaceranger-2.0.0/probe_set/Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv \ #Path to probe set
--feature-ref=/home/jdoe/spaceranger-2.0.0/antibody_refs/Visium_Human_Immune_Cell_Profiling_Panel_v1.0.csv\ #Path to Feature Reference CSV
--libraries=/home/jdoe/runs/mysample_libraries.csv \ #Path to library CSV file specifying both GEX and PEX FASTQ files
--cytaimage=/home/jdoe/runs/images/A1_sample345.tiff \ #Path to CytAssist image input
--darkimage=/home/jdoe/runs/images/IF_sample345.tiff \ #Path to IF microscope image input
--dapi-index=2 \ #Numeric value corresponding to the DAPI channel
--slide=V49J01-123 \ #Slide ID
--area=A1 \ #Capture area
--localcores=8 \ #Allowed cores in localmode
--localmem=64 #Allowed memory (GB) in localmode
The example code represents use of a brightfield microscope image in addition to CytAssist image. Loupe Browser's CytAssist Image Alignment and Manual Fiducial Alignment workflows are used to generate a single JSON file that contains both image and fiducial alignment information.
Note that both of the images used for alignment are passed to spaceranger count along with the following arguments.
cd /home/jdoe/runs
spaceranger count --id=sample345 \ #Output directory
--transcriptome=/home/jdoe/refdata/GRCh38-2020-A \ #Path to Reference
--probe-set=/home/jdoe/spaceranger-2.0.0/probe_set/Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv \ #Path to probe set
--feature-ref=/home/jdoe/spaceranger-2.0.0/antibody_refs/Visium_Human_Immune_Cell_Profiling_Panel_v1.0.csv\ #Path to Feature Reference CSV
--libraries=/home/jdoe/runs/mysample_libraries.csv \ #Path to library CSV file specifying both GEX and PEX FASTQ files
--cytaimage=/home/jdoe/runs/images/A1_sample345.tiff \ #Path to CytAssist image input
--image=/home/jdoe/runs/images/sample345.tiff \ #Path to brightfield image input
--slide=V49J01-123 \ #Slide ID
--area=A1 \ #Capture area
--loupe-alignment=sample345.json \ #Manual image registration and fiducial alignment file
--localcores=8 \ #Allowed cores in localmode
--localmem=64 #Allowed memory (GB) in localmode
When inputting Feature data to Space Ranger via the Libraries CSV file, you must declare the library_type of each library. Specific values for library_type will enable additional downstream processing, specifically Protein Expression. The following table outlines the types of libraries that can be specified and what they mean for the downstream processing.
| library_type | Description |
|---|---|
Antibody Capture | For use with experiments measuring protein expression levels via spatially barcoded antibody oligonucleotides. Includes secondary analysis of the spots using only the Protein Expression feature counts. This projection is available in an output file and in Loupe Browser. |
Gene Expression | Enables an analysis of gene expression changes. This mode also creates secondary analysis using only the Gene Expression counts and is available in an output file and in Loupe Browser. |
The Libraries CSV file declares the input FASTQ data for multiple libraries. This will include one library containing Spatial Gene Expression reads, and one library containing Protein Expression reads. This file is specified in spaceranger count using the --libraries flag. The following table describes what the content should be in the Libraries CSV file.
| Column Name | Description |
|---|---|
fastqs | A fully qualified path to the directory containing the demultiplexed FASTQ files for this sample. Analogous to the --fastqs arg to spaceranger count. This field does not accept comma-delimited paths. For multiple sets of fastqs for the same library, add an additional row, and use the use same library_type value. |
sample | Same as the sample arg to spaceranger count. Sample name assigned in the bcl2fastq sample sheet. |
library_type | The FASTQ data will be interpreted using the rows from the feature reference file that have a ‘feature_type’ that matches this library_type. This field is case-sensitive, and must match a valid library type as described in the Feature and library types section. Must be Gene Expression for the Gene Expression libraries or Antibody Capture for Protein Expression libraries. |
Gene expression + Protein Expression libraries - Single Set
In this example we've demultiplexed the sequencing data from two libraries named GEX_sample1 and Ab_sample1 on the bcl2fastq / mkfastq sample sheet. This generated two FASTQ files named GEX_sample1_S0_L001_001.fastq.gz and Ab_sample1_S0_L001_001.fastq.gz in the path /home/jdoe/runs (replace the path with the correct full path to the FASTQ files). Pass the FASTQ sample names to Space Ranger with the appropriate library types.
| fastqs | sample | library_type |
|---|---|---|
| /home/jdoe/runs/PATH/TO/GEX/FASTQs | GEX_sample1 | Gene Expression |
| /home/jdoe/runs/PATH/TO/PEX/FASTQs | Ab_sample1 | Antibody Capture |
Gene expression + Protein Expression libraries - Multiple Set
In this example we've demultiplexed the sequencing data from two libraries named GEX_sample1 and Ab_sample1 on the bcl2fastq / mkfastq sample sheet. The GEX library was sequenced on two flowcells generating an additional library named GEX_sample2. This generated three FASTQ files named GEX_sample1_S0_L001_001.fastq.gz, GEX_sample2_S0_L001_001.fastq.gz and Ab_sample1_S0_L001_001.fastq.gz in the path /home/jdoe/runs (replace the path with the correct full path to the FASTQ files). Pass the FASTQ sample names to Space Ranger with the appropriate library types.
| fastqs | sample | library_type |
|---|---|---|
| /home/jdoe/runs/PATH/TO/GEX/FASTQs | GEX_sample1 | Gene Expression |
| /home/jdoe/runs/PATH/TO/GEX/FASTQs | GEX_sample2 | Gene Expression |
| /home/jdoe/runs/PATH/TO/PEX/FASTQs | Ab_sample1 | Antibody Capture |
Probe set reference CSV file for human can be found in the probe_sets directory in the Space Ranger package. Note that only the highlighted probe set reference CSV files are compatible with Visium CytAssist Spatial Gene Expression workflow.
spaceranger-2.0.0/probe_sets/
├── Visium_Human_Transcriptome_Probe_Set_v1.0_GRCh38-2020-A.csv
├── Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv
└── Visium_Mouse_Transcriptome_Probe_Set_v1.0_mm10-2020-A.csv
A successful spaceranger count run concludes with a message similar to this:
- Run summary HTML: /home/jdoe/runs/sample345/outs/web_summary.html
- Outputs of spatial pipeline:
aligned_fiducials: /home/jdoe/runs/sample345/outs/spatial/aligned_fiducials.jpg
detected_tissue_image: /home/jdoe/runs/sample345/outs/spatial/detected_tissue_image.jpg
scalefactors_json: /home/jdoe/runs/sample345/outs/spatial/scalefactors_json.json
tissue_hires_image: /home/jdoe/runs/sample345/outs/spatial/tissue_hires_image.png
tissue_lowres_image: /home/jdoe/runs/sample345/outs/spatial/tissue_lowres_image.png
cytassist_image: /home/jdoe/runs/sample345/outs/spatial/cytassist_image.tiff
aligned_tissue_image: /home/jdoe/runs/sample345/outs/spatial/aligned_tissue_image.jpg
tissue_positions: /home/jdoe/runs/sample345/outs/spatial/tissue_positions.csv
spatial_enrichment: /home/jdoe/runs/sample345/outs/spatial/spatial_enrichment.csv
barcode_fluorescence_intensity: /home/jdoe/runs/sample345/outs/spatial/barcode_fluorescence_intensity.csv
- Run summary CSV: /home/jdoe/runs/sample345/outs/metrics_summary.csv
- Correlation values between isotypes and Antibody features: null
- BAM: /home/jdoe/runs/sample345/outs/possorted_genome_bam.bam
- BAM BAI index: /home/jdoe/runs/sample345/outs/possorted_genome_bam.bam.bai
- BAM CSI index: null
- Filtered feature-barcode matrices MEX: /home/jdoe/runs/sample345/outs/filtered_feature_bc_matrix
- Filtered feature-barcode matrices HDF5: /home/jdoe/runs/sample345/outs/filtered_feature_bc_matrix.h5
- Unfiltered feature-barcode matrices MEX: /home/jdoe/runs/sample345/outs/raw_feature_bc_matrix
- Unfiltered feature-barcode matrices HDF5: /home/jdoe/runs/sample345/outs/raw_feature_bc_matrix.h5
- Secondary analysis output CSV: /home/jdoe/runs/sample345/outs/analysis
- Per-molecule read information: /home/jdoe/runs/sample345/outs/molecule_info.h5
- Loupe Browser file: /home/jdoe/runs/sample345/outs/cloupe.cloupe
- Feature Reference: null
- Target Panel file: null
- Probe Set file: /home/jdoe/runs/sample345/outs/probe_set.csv
Pipestance completed successfully!
The output of the pipeline is contained in a folder named with the sample ID specified using --id (e.g. sample345). If this folder already exists, in a rerun with the original parameters, spaceranger will assume it is an existing pipestance and attempt to resume running it. The subfolder named outs contains the main pipeline output files.