10x
Support
Search Support
Contact us
10x Genomics Support/Space Ranger/Analysis/

Visium CytAssist-enabled Analysis with spaceranger count (GEX + PEX)

Space Ranger v2.1 or later</b> is required to analyze both gene and protein data with spaceranger count.

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 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
  • The feature reference CSV file specified using --feature-ref flag

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_typeDescription
Antibody CaptureFor 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 ExpressionEnables 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 NameDescription
fastqsA 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.
sampleSame as the sample arg to spaceranger count. Sample name assigned in the bcl2fastq sample sheet.
library_typeThe 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.
Each unique sample id requires a separate line in the library CSV file.

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.

fastqssamplelibrary_type
/home/jdoe/runs/PATH/TO/GEX/FASTQsGEX_sample1Gene Expression
/home/jdoe/runs/PATH/TO/PEX/FASTQsAb_sample1Antibody 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.

fastqssamplelibrary_type
/home/jdoe/runs/PATH/TO/GEX/FASTQsGEX_sample1Gene Expression
/home/jdoe/runs/PATH/TO/GEX/FASTQsGEX_sample2Gene Expression
/home/jdoe/runs/PATH/TO/PEX/FASTQsAb_sample1Antibody 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.