HOME  ›   pipelines
If your question is not answered here, please email us at:  ${email.software}

10x Genomics
Visium Spatial Gene Expression

Molecule Info

The spaceranger pipeline outputs an HDF5 file containing per-molecule information for all molecules that contain a valid barcode, valid UMI, and were assigned with high confidence to a gene. This HDF5 file contains data corresponding to the observed molecules, as well as data about the libraries, features (genes), and barcode lists used for the analysis. Refer to the HDF5 Matrix format for more general information.

Table of Contents

HDF5 File Hierarchy

molecule_info.h5
│   ├── file_version
│   ├── filetype
├── barcode_idx
├── barcode_info [HDF5 group]
│   ├── genomes
│   └── pass_filter
├── barcodes
├── count
├── feature_idx
├── features [HDF5 group]
│   ├── _all_tag_keys
│   ├── feature_type
│   ├── genome
│   ├── id
│   ├── name
│   └── target_sets [HDF5 group]
│       ├── target panel CSV [For Targeted GEX]
│       └── probe set reference CSV [For Visium FFPE]   
├── gem_group
├── library_idx
├── library_info
├── metrics_json [HDF5 group]
├── umi
└── umi_type

The contents of the .h5 file can be examined using HDFView software or the h5dump command.

h5dump -n molecule_info.h5
 
HDF5 "molecule_info.h5" {
FILE_CONTENTS {
 group      /
 dataset    /barcode_idx
 group      /barcode_info
 dataset    /barcode_info/genomes
 dataset    /barcode_info/pass_filter
 dataset    /barcodes
 dataset    /count
 dataset    /feature_idx
 group      /features
 dataset    /features/_all_tag_keys
 dataset    /features/feature_type
 dataset    /features/genome
 dataset    /features/id
 dataset    /features/name
 dataset    /gem_group
 dataset    /library_idx
 dataset    /library_info
 dataset    /metrics_json
 dataset    /umi
 dataset    /umi_type
 }

Per-molecule columns

The following HDF5 datasets in the molecule info file correspond to columns of a table. Each row of that table corresponds to a unique (UMI, spot-barcode, feature) tuple indicating the feature best supported by the reads (i.e., including PCR duplicates) assigned to that UMI and spot-barcode.

ColumnTypeDescription
barcode_idxuint64A zero-based index into the barcodes dataset (see next section), indicating the spot-barcode assigned to this putative molecule.
countuint32Number of reads associated with this putative molecule that were confidently mapped to the assigned feature.
feature_idxuint32A zero-based index into the feature list (see next section), indicating the feature to which this putative molecule was assigned.
gem_groupuint16Integer label that is currently one (1) for all Space Ranger output.
library_idxuint16Integer label that is currently one (1) for all Space Ranger output.
umiuint322-bit encoded (see note below) processed (i.e. corrected) UMI sequence.
umi_typeuint32A boolean array specifying whether the molecule aligned to an exonic (1) or intronic (0) region of the associated feature.

Reference columns

In addition, the molecule info file has datasets corresponding to information about the libraries, barcode list(s), and feature set(s) that were used in the analysis.

Experiment reference

At the top level of the HDF5 file hierarchy, the barcodes and library_info datasets provide information about the experiments contained in this analysis:

DatasetTypeDescription
barcodesstringA list of all spot-barcodes associated with this experiment (including those that were not observed). The barcode_idx column described in the previous section contains indices into this list of barcodes. Each spot-barcode sequence has a trailing digit that is currently one (1) in output generated from Space Ranger (e.g., AGAATGGTCTGCAT-1).
library_infostringA JSON-formatted array of objects, where each object contains metadata for a single library. Each library will at a minimum contain the metadata library_id, library_type, and gem_group

Observed spot-barcodes

The HDF5 group barcode_info gives information regarding the barcodes determined to be underneath the tissue. This HDF5 group contains two columns:

DatasetTypeDescription
genomesstringA list of all genome references used for gene expression libraries in this analysis.
pass_filteruint64A matrix with three columns that contains one row per passing spot-barcode. Each row is a tuple (barcode_idx, library_idx, genome_idx), where genome_idx is an index into the genomes dataset.

Feature reference

The HDF5 group features contains information regarding the feature reference(s) used for the analysis. The datasets within the features group represent columns in a table containing one row per feature (gene). Values in the feature_idx column described in the previous section provide indices into the rows of this hypothetical table.

In addition to the columns described below, user-specified tags may also be present. The dataset _all_tag_keys contains a list of user-specified tags as well as built-in tags (genome).

ColumnTypeDescription
feature_typestringThe type of feature reference to which this feature belongs. Currently Visum only supports Gene Expression features.
genomestringThe genome reference for a given feature (e.g., "GRCh38" or "mm10").
idstringThe unique id corresponding to this feature (for example, an Ensembl gene ID).
namestringA human-readable name associated with this feature (for example, the common name associated with a gene).

The features group also contains an HDF5 group target_sets which contain the probe set reference CSV for Visium FFPE samples and target panel CSV for Targeted Gene Expression. When a target gene panel is present, indices of the target genes are stored inside target_sets, in an HDF5 dataset named after the target gene panel (e.g., "Human Gene Signature").

2-bit encoding

The UMI sequences are 2-bit encoded as follows:

Note that the spot-barcode sequences do not have this encoding. Instead, they are stored as plain strings in the library_info HDF5 group.

Metrics JSON HDF5 group

The metrics_json dataset contains pipeline metrics in JSON format that are used internally by Space Ranger. Users should view metrics using the Space Ranger metrics outputs.