The spaceranger count and spaceranger aggr pipelines run in a directory named after the --id argument (the "pipestance" directory). Output files appear in the outs/ subdirectory within the pipestance directory.
The exact output files produced for a given pipestance depend on:
- the Space Ranger version used
- which pipeline was used (
spaceranger countorspaceranger aggr) - the parameters specified to the pipeline
- whether or not the CytAssist instrument was used
- whether brightfield or fluoresence images were provided
- which Visium assay was used
As an example, a spaceranger count analysis will display a message similar to the following after completion:
Outputs: - 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: null aligned_tissue_image: null 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: null - 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: null Pipestance completed successfully!
In this case:
/home/jdoe/runs/is where the pipeline was run/home/jdoe/runs/sample345/is the pipestance directory containing pipeline metadata/home/jdoe/runs/sample345/outs/contains the final pipeline output filesnullmeans this particular file type was not generated for this run
When running spaceranger count on Visium v1/v2 Spatial Gene Expression libraries, the following files can be found within the outs/ subfolder:
| File or Directory Name | Description |
|---|---|
web_summary.html | Run summary metrics and plots in HTML format |
cloupe.cloupe | Loupe Browser visualization and analysis file |
spatial/ | Folder containing outputs that capture the spatiality of the data. |
analysis/ | Folder containing secondary analysis data including graph-based clustering and K-means clustering (K = 2-10); differential gene expression between clusters; PCA, t-SNE, and UMAP dimensionality reduction. |
metrics_summary.csv | Run summary metrics in CSV format |
probe_set.csv | Copy of the input probe set reference CSV file. Present for Visium FFPE and CytAssist workflow |
possorted_genome_bam.bam | Indexed BAM file containing position-sorted reads aligned to the genome and transcriptome, annotated with barcode information |
possorted_genome_bam.bam.bai | Index for possorted_genome_bam.bam. In cases where the reference transcriptome is generated from a genome with very long chromosomes (>512 Mbp), Space Ranger v2.0+ generates a possorted_genome_bam.bam.csi index file instead. |
filtered_feature_bc_matrix/ | Contains only tissue-associated barcodes in MEX format. Each element of the matrix is the number of UMIs associated with a feature (row) and a barcode (column). This file can be input into third-party packages and allows users to wrangle the barcode-feature matrix (e.g. to filter outlier spots, run dimensionality reduction, normalize gene expression). |
filtered_feature_bc_matrix.h5 | Same information as filtered_feature_bc_matrix/ but in HDF5 format. |
raw_feature_bc_matrices/ | Contains all detected barcodes in MEX format. Each element of the matrix is the number of UMIs associated with a feature (row) and a barcode (column). |
raw_feature_bc_matrix.h5 | Same information as raw_feature_bc_matrices/ in HDF5 format. |
raw_probe_bc_matrix.h5 | Contains UMI counts of each probe for all detected barcodes in HDF5 format. Only produced when running pipelines for probe-based assays. |
molecule_info.h5 | Contains per-molecule information for all molecules that contain a valid barcode, valid UMI, and were assigned with high confidence to a gene or protein barcode. This file is required for additional analysis spaceranger pipelines including aggr, targeted-compare and targeted-depth. |
Space Ranger v2.1 introduced support for Gene and Protein Expression (v2 slides only), and there are a few variations from the list above. For more information, see the Protein Expression outputs.
When spaceranger count is run on Visium HD data, outputs follow a similar format as described above. The biggest difference is that Visium HD data are binned by default. Therefore, the outputs have a hierarchical structure to match different bin levels.
| File or Directory Name | Description |
|---|---|
binned_outputs | By default, this directory has three subdirectories: square_002um, square_008um, and square_016um. Each directory contains filtered_feature_bc_matrix, raw_feature_bc_matrix, spatial, filtered_feature_bc_matrix.h5, and raw_feature_bc_matrix.h5. The analysis directory is only provided at 8 and 16 µm bin size. The cloupe.cloupe is only provided at 8 µm bin size. The raw_probe_bc_matrix.h5 is only provided at 2 µm resolution. |
cloupe_008um.cloupe | Symlink to the .cloupe file at 8 µm bin size |
feature_slice.h5 | A new file type, specific to Visium HD, to support efficient fetching of 2 µm resolution image slices for a single gene or multiple genes. See this page for more details. |
metrics_summary.csv | Run summary metrics in CSV format |
molecule_info.h5 | Contains per-molecule information for all molecules that contain a valid barcode, valid UMI, and were assigned with high confidence to a gene barcode or bin. |
probe_set.csv | Copy of the input probe set reference CSV file. |
spatial | Folder containing outputs that capture the spatiality of the data. See the Spatial Outputs page for more details. |
web_summary.html | Run summary metrics and plots in HTML format |
For convenient multi-sample analysis, the spaceranger aggr pipeline generates output files that contain all the data from the individual input jobs, aggregated into single output files. The capture area suffix of each barcode is updated to prevent barcode collisions.
Visium HD is not supported with
spaceranger aggr. A successful spaceranger aggr run should conclude with a message similar to this:
Outputs:
- Aggregation metrics summary HTML: /opt/runs/AGG123/outs/web_summary.html
- Aggregation metrics summary JSON: /opt/runs/AGG123/outs/summary.json
- Secondary analysis output CSV: /opt/runs/AGG123/outs/analysis
- Filtered feature-barcode matrices MEX: /opt/runs/AGG123/outs/filtered_feature_bc_matrix
- Filtered feature-barcode matrices HDF5: /opt/runs/AGG123/outs/filtered_feature_bc_matrix.h5
- Copy of the input aggregation CSV: /opt/runs/AGG123/outs/aggregation.csv
- Loupe Browser file: /opt/runs/AGG123/outs/cloupe.cloupe
- Aggregated tissue positions list: /opt/runs/AGG123/outs/aggr_tissue_positions.csv
- Spatial folder containing spatial images and scalefactors: /opt/runs/AGG123/outs/spatial
Pipestance completed successfully!
Upon completion, all the main pipeline outputs can be found in the outs/ subfolder which has the following structure:
outs
├── aggregation.csv
├── aggr_tissue_positions.csv
├── analysis
│ ├── clustering
│ ├── diffexp
│ ├── pca
│ ├── tsne
│ └── umap
├── cloupe.cloupe
├── filtered_feature_bc_matrix
│ ├── barcodes.tsv.gz
│ ├── features.tsv.gz
│ └── matrix.mtx.gz
├── filtered_feature_bc_matrix.h5
├── spatial
│ ├── LV123
│ │ ├── scalefactors_json.json
│ │ ├── tissue_hires_image.png
│ │ └── tissue_lowres_image.png
│ ├── LB456
│ │ ├── scalefactors_json.json
│ │ ├── tissue_hires_image.png
│ │ └── tissue_lowres_image.png
│ └── LP789
│ ├── scalefactors_json.json
│ ├── tissue_hires_image.png
│ └── tissue_lowres_image.png
├── summary.json
└── web_summary.html
The files are similar to the spaceranger count pipeline outputs. The aggr pipeline also outputs a copy of the input aggregation.csv.