Support homeSpace RangerAnalysis
Visium CytAssist-enabled Analysis with spaceranger count (GEX only)

Visium CytAssist-enabled Analysis with spaceranger count (GEX only)

Space Ranger's pipelines analyze sequencing data produced from Visium Spatial Gene Expression solutions. The Visium CytAssist instrument aids in the transfer of features from the FFPE, FxF, or FF tissue section on a standard glass slides to the Visium CytAssist Spatial Gene Expression Slide. The workflow diagram shows all the required inputs and the corresponding spaceranger flags for analyzing Visium CytAssist data:

The spaceranger count pipeline is run on each individual Capture Area in the Visium slide. The required inputs are:

  • The FASTQ files for a given capture area (--fastqs)
    • If starting with Illumina BCL output folder, follow the instructions on running spaceranger mkfastq to generate FASTQ files
    • For help on which arguments to use to target a particular set of FASTQs, consult Specifying Input FASTQ Files
  • The corresponding CytAssist image in TIFF with optional microscope image in either TIFF, QPTIFF or JPEG format
    • --cytaimage for image captured by CytAssist instrument (contains fiducial frame)
    • --image for brightfield microscope image
    • --darkimage for dark background fluorescence microscope image
    • --colorizedimage for composite colored fluorescence microscope image
  • The slide layout GPR file specified by
    • --slide & --area if spaceranger has access to internet
    • --slidefile, --slide & --area if spaceranger has no access to internet. The slide layout file is directly downloaded
    • --unknown-slide if 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-set flag

For a list of accepted arguments, see the Command Line Argument Reference, or run spaceranger count --help. 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.

Select the section corresponding to the imaging workflow.

There are two possible workflow variations depending on whether or not a high resolution microscopy image of the tissue section on the standard glass is supplied. Note that success of the automatic image processing pipeline is based on the assumption that the tissue morphology and overall shape on the microscope image matches that captured by CytAssist. The presence of tissue folds, tears, and other artifacts that prevent the CytAssist image from representing the tissue on the slide can lead to potential problems with pipeline processing.

1. CytAssist Image only


To generate spatial feature counts for a single library using automatic fiducial alignment and tissue detection on CytAssist image input, run spaceranger count with the following arguments. The highlighted code indicates inputs that need not be changed.

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
                  --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
                  --sample=mysample \ #Sample name from FASTQ filename
                  --cytaimage=/home/jdoe/runs/images/A1_sample345.tiff \ #Path to CytAssist image input
                  --slide=V49J01-123 \ #Slide ID
                  --area=A1 \ #Capture area
                  --localcores=8 \ #Allowed cores in localmode
                  --localmem=64  #Allowed memory (GB) in localmode

2. CytAssist + Microscope Image


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 CytAssist image. The highlighted code indicates inputs that need not be changed.

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
                  --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
                  --sample=mysample \ #Sample name from FASTQ filename
                  --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

There are three possible workflow variations, depending on whether or not a high resolution microscopy image of the tissue section on the standard glass slide was supplied, and the types of manual alignment performed in Loupe Browser. The following examples use Brightfield microscope image. The arguments to specify the fluorescence image can be either --darkimage or --colorizedimage depending on the image format. Note that the brightfield CytAssist image, which has the fiducial frame, is used for fiducial alignment and tissue detection workflow. Details about the different supported fluorescence image formats are described in Image Recommendations.

1. CytAssist Image + Microscope Image: Manual CytAssist Image Alignment


If the automatic image registration between the CytAssist and microscope images is not satisfactory, use Loupe's CytAssist Image Alignment workflow to generate a image alignment JSON file. Both of the images used for alignment should also be passed to spaceranger count along with the following arguments.

1cd /home/jdoe/runs
2spaceranger count --id=sample345 \ #Output directory
3                  --transcriptome=/home/jdoe/refdata/GRCh38-2020-A \ #Path to Reference
4                  --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
5                  --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
6                  --sample=mysample \ #Sample name from FASTQ filename
7                  --cytaimage=/home/jdoe/runs/images/A1_sample345.tiff \ #Path to CytAssist image input
8                  --image=/home/jdoe/runs/images/sample345.tiff \ #Path to brightfield image input
9                  --slide=V49J01-123 \ #Slide ID
10                  --area=A1 \ #Capture area
11                  --loupe-alignment=sample345.json \ #Manual image registration file
12                  --localcores=8 \ #Allowed cores in localmode
13                  --localmem=64  #Allowed memory (GB) in localmode

2. CytAssist Image + Microscope Image: Manual CytAssist Image Alignment + Fiducial Alignment


In some cases, the automatic image registration between the CytAssist and microscope images, or the automatic fiducial alignment and tissue detection on the CytAssist image, may not be satisfactory. In that scenario, both Loupe Browser's [CytAssist Image Alignment] and Manual Fiducial Alignment workflows can be 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.

1cd /home/jdoe/runs
2spaceranger count --id=sample345 \ #Output directory
3                  --transcriptome=/home/jdoe/refdata/GRCh38-2020-A \ #Path to Reference
4                  --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
5                  --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
6                  --sample=mysample \ #Sample name from FASTQ filename
7                  --cytaimage=/home/jdoe/runs/images/A1_sample345.tiff \ #Path to CytAssist image input
8                  --image=/home/jdoe/runs/images/sample345.tiff \ #Path to brightfield image input
9                  --slide=V49J01-123 \ #Slide ID
10                  --area=A1 \ #Capture area
11                  --loupe-alignment=sample345.json \ #Manual image registration and fiducial alignment file
12                  --localcores=8 \ #Allowed cores in localmode
13                  --localmem=64  #Allowed memory (GB) in localmode

3. CytAssist Image only: Manual Fiducial Alignment


For CytAssist image-only input, there is also the option to run the manual fiducial alignment workflow in Loupe Browser to generate a fiducial alignment and tissue assignment JSON file. Note that it is possible to pass a microscope image input in this configuration for automatic image registration in Space Ranger. The spaceranger count pipeline can be run 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
                  --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \ #Path to FASTQs
                  --sample=mysample \ #Sample name from FASTQ filename
                  --cytaimage=/home/jdoe/runs/images/A1_sample345.tiff \ #Path to CytAssist image input
                  --slide=V49J01-123 \ #Slide ID
                  --area=A1 \ #Capture area
                  --loupe-alignment=sample345.json \ #Manual fiducial alignment file
                  --localcores=8 \ #Allowed cores in localmode
                  --localmem=64  #Allowed memory (GB) in localmode

Probe set reference CSV files 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.

1spaceranger-2.0.0/probe_sets/
2├── Visium_Human_Transcriptome_Probe_Set_v1.0_GRCh38-2020-A.csv
3├── Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv
4└── 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.