Skip to main content

File Types and File Formats

This page describes, for each file type, the configuration options and the file formatting requirements.

The file types and file formats listed here are natively (i.e., can be loaded directly without a conversion step) supported by Vitessce. To use other file formats with Vitessce, there are two options: convert to format(s) supported by Vitessce, or develop a plugin file type.

tip

If you encounter any issues, please check out our data troubleshooting page before opening an issue.

info

The JSON file definition snippets found on this page would be specified as objects in the array datasets[].files[] in the JSON view configuration.

CSV​

obsFeatureMatrix.csv​

An observation-by-feature matrix stored in a CSV file. Rows represent observations, columns represent features. The first column stores the observation index (unique ID for each observation). For example, the file contents might look like:

cell_idCD33MYC
cell_115.10.0
cell_20.021.4
cell_30.00.0
...,
{
  "fileType": "obsFeatureMatrix.csv",
  "url": "https://example.com/my_expression_matrix.csv",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  }
},
...

obsEmbedding.csv​

A three-column (minimum; the file may contain extra columns) CSV file. One column stores the observation index (unique ID for each observation) and the other two store 2D embedding coordinates. The column names are configurable. For example, the file contents might look like:

cell_idUMAP_1UMAP_2
cell_11.52.7
cell_23.11.2
.........
...,
{
  "fileType": "obsEmbedding.csv",
  "url": "https://example.com/my_umap.csv",
  "coordinationValues": {
    "obsType": "cell",
    "embeddingType": "UMAP"
  },
  "options": {
    // The column containing the observation index.
    "obsIndex": "cell_id",
    // The two columns containing the embedding coordinates.
    "obsEmbedding": ["UMAP_1", "UMAP_2"]
  }
},
...

obsPoints.csv​

A three-column (minimum; the file may contain extra columns) CSV file. One column stores the observation index (unique ID for each observation) and the other two store (x, y) spatial coordinates. The column names are configurable. For example, the file contents might look like:

cell_idXY
cell_11.52.7
cell_23.11.2
.........
...,
{
  "fileType": "obsPoints.csv",
  "url": "https://example.com/my_cell_coordinates.csv",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // The column containing the observation index.
    "obsIndex": "cell_id",
    // The two columns containing the (x, y) coordinates.
    "obsPoints": ["X", "Y"]
  }
},
...

obsSpots.csv​

A three-column (minimum; the file may contain extra columns) CSV file. One column stores the observation index (unique ID for each observation) and the other two store (x, y) spatial coordinates. The column names are configurable. For example, the file contents might look like:

cell_idXY
cell_11.52.7
cell_23.11.2
.........
...,
{
  "fileType": "obsSpots.csv",
  "url": "https://example.com/my_cell_coordinates.csv",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // The column containing the observation index.
    "obsIndex": "cell_id",
    // The two columns containing the (x, y) coordinates.
    "obsSpots": ["X", "Y"]
  }
},
...

obsLocations.csv​

A three-column (minimum; the file may contain extra columns) CSV file. One column stores the observation index (unique ID for each observation) and the other two store (x, y) spatial coordinates. The column names are configurable. For example, the file contents might look like:

cell_idXY
cell_11.52.7
cell_23.11.2
.........
...,
{
  "fileType": "obsLocations.csv",
  "url": "https://example.com/my_cell_coordinates.csv",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // The column containing the observation index.
    "obsIndex": "cell_id",
    // The two columns containing the (x, y) coordinates.
    "obsLocations": ["X", "Y"]
  }
},
...

obsSets.csv​

Maps each observation to membership in one or more sets. Typically used to assign cells to cell type labels or cell cluster IDs. To allow for multiple groups of sets to be be specified, options takes an array.

If a group of sets is organized as a flat list, then "column" points to a column containing string labels. Alternatively, if organized as a hierarchy, then "column" can point to an array of columns, progressing from coarser to finer labels.

For example, the file contents might look like:

cell_idleidencell_type_coarsecell_type_finepred_cell_typepred_score
cell_11ImmuneB cellB cell0.81
cell_22ImmuneT cellT cell0.99
cell_32ImmuneT cellMacrophage0.21
cell_43NeuronExcitatory neuronInhibitory neuron0.25
..................
...,
{
  "fileType": "obsSets.csv",
  "url": "https://example.com/my_cell_set_membership.csv",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    "obsIndex": "cell_id",
    "obsSets": [
      {
        "name": "Leiden Clustering",
        "column": "leiden"
      },
      {
        "name": "Cell Type Annotations",
        "column": ["cell_type_coarse", "cell_type_fine"]
      },
      {
        "name": "Predicted Cell Types",
        "column": "pred_cell_type",
        "scoreColumn": "pred_score"
      }
    ]
  }
},
...

obsLabels.csv​

A two-column (minimum; the file may contain extra columns) CSV file. One column stores the observation index (unique ID for each observation) and the other stores string labels. The column names are configurable. For example, the file contents might look like:

cell_idalt_cell_id
cell_1ATGC
cell_2GTTA
......
...,
{
  "fileType": "obsLabels.csv",
  "url": "https://example.com/my_cell_barcodes.csv",
  "coordinationValues": {
    "obsType": "cell",
    "obsLabelsType": "Alternate cell ID"
  },
  "options": {
    // The column containing the observation index.
    "obsIndex": "cell_id",
    // The column containing the string labels.
    "obsLabels": "alt_cell_id"
  }
},
...

featureLabels.csv​

A two-column (minimum; the file may contain extra columns) CSV file. One column stores the feature index (unique ID for each feature) and the other stores string labels. The column names are configurable. For example, the file contents might look like:

ensembl_gene_idgene_symbol
ENSG00000105383CD33
ENSG00000136997MYC
......
...,
{
  "fileType": "featureLabels.csv",
  "url": "https://example.com/my_gene_symbols.csv",
  "coordinationValues": {
    "featureType": "gene",
    "featureLabelsType": "Gene symbol"
  },
  "options": {
    // The column containing the feature index.
    "featureIndex": "ensembl_gene_id",
    // The column containing the string labels.
    "featureLabels": "gene_symbol"
  }
},
...

sampleSets.csv​

Maps each sample to membership in one or more sets.

If a group of sets is organized as a flat list, then "column" points to a column containing string labels. Alternatively, if organized as a hierarchy, then "column" can point to an array of columns, progressing from coarser to finer labels.

For example, the file contents might look like:

donor_iddisease_state
donor_1Healthy reference
donor_2Diabetes
donor_3Diabetes
donor_4Healthy reference
......
...,
{
  "fileType": "sampleSets.csv",
  "url": "https://example.com/my_sample_set_membership.csv",
  "coordinationValues": {
    "sampleType": "donor"
  },
  "options": {
    "sampleIndex": "donor_id",
    "sampleSets": [
      {
        "name": "Disease state",
        "column": "disease_state"
      }
    ]
  }
},
...

AnnData-Zarr​

While Zarr is an efficient format for storing multidimensional arrays, it does not dictate how multiple individual arrays are organized in a larger data structure. AnnData fills this gap by defining a data structure for observation-by-feature matrices and many types of associated metadata. This works nicely for the single-cell use case: think of cells as observations (rows). AnnData objects can be saved to Zarr format.

For single-cell data visualization, we typically use the following fields of the AnnData object:

  • X: the observation-by-feature (e.g., cell-by-gene) expression matrix, stored as a 2D array
  • obs: a DataFrame where the rows match the rows of X (same number and ordering of rows in obs as rows in X)
  • var: a DataFrame where the rows match the columns of X (same number and ordering of rows in var as columns in X)
  • obsm: a dictionary storing named arrays
    • keys are strings, with the convention to begin with the prefix X_ (e.g., X_umap to store an array of UMAP coordinates)
    • values are multidimensional arrays where the rows (i.e., elements of the zeroth dimension) match the rows of X
  • layers: a dictionary storing named arrays
    • keys are strings, with the convention to begin with the prefix X_
    • values are 2D arrays with the same shape as X

To learn more, visit the AnnData documentation.

obsFeatureMatrix.anndata.zarr​

An observation-by-feature matrix with observations along the obs axis (rows) and features along the var axis (columns). Typically stored in adata.X, but the "path" option allows pointing to any array within the AnnData object.

...,
{
  "fileType": "obsFeatureMatrix.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    // Should point to the observation-by-feature matrix
    "path": "X"
  }
},
...

Data types​

Currently, Vitessce internally normalizes data to uint8 (sometimes abbreviated u1), to improve performance. (In the future, we hope to add the ability to perform multiple types of normalization on-the-fly within Vitessce.) If you would like full control over the normalization procedure, we recommend using the layers feature of AnnData to store a copy of adata.X that has been pre-normalized and cast to uint8, while keeping adata.X with its original dtype:

from vitessce.data_utils import to_uint8

# ...
adata.layers['X_uint8'] = to_uint8(adata.X, norm_along="global")
# ...
...,
{
  "fileType": "obsFeatureMatrix.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    // Should point to the observation-by-feature matrix
    "path": "layers/X_uint8"
  }
},
...

Sub-matrix​

By default, rendering an observation-by-feature matrix in a heatmap requires fetching the entire matrix over the network which can result in a long initial load time and a large network request. There are two ways to alleviate this issue when using the obsFeatureMatrix.anndata.zarr file type:

  • Load (and therefore transfer over the network) only a subset of the matrix initially ("initialFeatureFilterPath")
  • Store a smaller matrix in an obsm array, and load that smaller matrix ("featureFilterPath")

Initialization-only filtering​

import scanpy as sc

# ...
sc.pp.highly_variable_genes(adata, n_top_genes=200)
# ...
...,
{
  "fileType": "obsFeatureMatrix.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    // Should point to the observation-by-feature matrix
    "path": "X",
    // If you would like to limit the amount of data loaded
    // initially (specifically in the heatmap),
    // then "initialFeatureFilterPath" should point to a boolean array
    // that indicates which features to load initially.
    "initialFeatureFilterPath": "var/highly_variable"
  }
},
...

Always filtering​

import scanpy as sc

# ...
sc.pp.highly_variable_genes(adata, n_top_genes=200)
adata.obsm['X_subset'] = adata[:, adata.var['highly_variable']].X
# ...
...,
{
  "fileType": "obsFeatureMatrix.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    // Should point to the observation-by-feature matrix
    "path": "obsm/X_subset",
    // If the matrix specified in "path" is a subset of X,
    // then "featureFilterPath" must point to a boolean array
    // that indicates which features are contained in the subsetted matrix.
    "featureFilterPath": "var/highly_variable"
  }
},
...

obsEmbedding.anndata.zarr​

A two-column array with entries along the obs axis. The two columns store 2D embedding coordinates. For example, the contents of adata.obsm['X_umap'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsEmbedding.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "embeddingType": "UMAP"
  },
  "options": {
    // Should point to an array of (d1, d2) coordinate pairs, one coordinate pair per obs/cell.
    "path": "obsm/X_umap",
    // Dimension indices are optional. By default, [0, 1].
    "dims": [0, 1]
  }
},
...

obsPoints.anndata.zarr​

A two-column array with entries along the obs axis. The two columns store (x, y) spatial coordinates. For example, the contents of adata.obsm['X_spatial'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsPoints.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "molecule"
  },
  "options": {
    // Should point to an array of (x, y) coordinate pairs, one coordinate pair per obs/cell.
    "path": "obs/X_spatial"
  }
},
...

obsSpots.anndata.zarr​

A two-column array with entries along the obs axis. The two columns store (x, y) spatial coordinates. For example, the contents of adata.obsm['X_spatial'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsSpots.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "bead"
  },
  "options": {
    // Should point to an array of (x, y) coordinate pairs, one coordinate pair per obs/cell.
    "path": "obs/X_spatial"
  }
},
...

obsSets.anndata.zarr​

Maps each observation to membership in one or more sets. Typically used to assign cells to cell type labels or cell cluster IDs. To allow for multiple groups of sets to be be specified, options takes an array.

If a group of sets is organized as a flat list, then "path" points to a column containing string labels. Alternatively, if organized as a hierarchy, then "path" can point to an array of columns, progressing from coarser to finer labels.

For example, the contents of adata.obs might look like:

indexleidencell_type_coarsecell_type_finepred_cell_typepred_score
cell_11ImmuneB cellB cell0.81
cell_22ImmuneT cellT cell0.99
cell_32ImmuneT cellMacrophage0.21
cell_43NeuronExcitatory neuronInhibitory neuron0.25
..................
...,
{
  "fileType": "obsSets.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": [
    {
      "name": "Leiden Clustering",
      "path": "obs/leiden"
    },
    {
      "name": "Cell Type Annotations",
      "path": ["obs/cell_type_coarse", "obs/cell_type_fine"]
    },
    {
      "name": "Predicted Cell Types",
      "path": "obs/pred_cell_type",
      "scorePath": "obs/pred_score"
    }
  ]
},
...

obsSegmentations.anndata.zarr​

...,
{
  "fileType": "obsSegmentations.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to an array of polygon vertices, one polygon per obs/cell.
    "path": "obs/X_segmentations"
  }
},
...

obsLabels.anndata.zarr​

A column containing string labels along the obs axis. For example, the contents of adata.obs['alt_cell_id'] might look like:

index
cell_1     ATCGC
cell_2     TCGGC
cell_3     TTTCA
Name: alt_cell_id, dtype: object
...,
{
  "fileType": "obsLabels.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "obsLabelsType": "Alternate cell ID"
  },
  "options": {
    // Should point to a string column
    "path": "obs/alt_cell_ids"
  }
},
...

obsLocations.anndata.zarr​

A two-column array with entries along the obs axis. The two columns store (x, y) spatial coordinates. For example, the contents of adata.obsm['X_spatial'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsLocations.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to an array of (x, y) coordinate pairs, one coordinate pair per obs/cell.
    "path": "obs/X_spatial"
  }
},
...

featureLabels.anndata.zarr​

A column containing string labels along the var axis. For example, the contents of adata.var['gene_symbol'] might look like:

index
ENSG00000152128     TMEM163
ENSG00000153086     ACMSD
ENSG00000082258     CCNT2
ENSG00000176601     MAP3K19
ENSG00000115839     RAB3GAP1
Name: gene_symbol, dtype: object
...,
{
  "fileType": "featureLabels.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "featureType": "gene",
    "featureLabelsType": "Gene symbol"
  },
  "options": {
    // Should point to a string column
    "path": "var/gene_symbol"
  }
},
...

sampleEdges.anndata.zarr​

A column containing string labels along the obs axis, which maps observations to samples. For example, the contents of adata.obs['donor_id'] might look like:

index
cell_1     donor_1
cell_2     donor_1
cell_3     donor_2
Name: donor_id, dtype: object
...,
{
  "fileType": "sampleEdges.anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "sampleType": "donor"
  },
  "options": {
    "path": "obs/donor_id"
  }
},
...

sampleSets.anndata.zarr​

Maps each sample to membership in one or more sets.

If a group of sets is organized as a flat list, then "column" points to a column containing string labels. Alternatively, if organized as a hierarchy, then "column" can point to an array of columns, progressing from coarser to finer labels.

For example, the file contents might look like:

donor_iddisease_state
donor_1Healthy reference
donor_2Diabetes
donor_3Diabetes
donor_4Healthy reference
......
...,
{
  "fileType": "sampleSets.anndata.zarr",
  "url": "https://example.com/my_sample_adata.zarr",
  "coordinationValues": {
    "sampleType": "donor"
  },
  "options": {
    "sampleSets": [
      {
        "name": "Disease State",
        "path": "disease_state"
      }
    ]
  }
},
...

comparisonMetadata.anndata.zarr​

Provides metadata about comparative analyses that have been pre-computed and stored in the AnnData object.

...,
{
  "fileType": "comparisonMetadata.anndata.zarr",
  "url": "https://example.com/my_comparative_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "sampleType": "sample"
  },
  "options": {
    "path": "uns/comparison_metadata"
  }
},
...

comparativeFeatureStats.anndata.zarr​

Per-feature statistics that have been pre-computed and stored in the AnnData object. Rather than pointing to the location of the results directly, with this file type, we point to the comparison metadata location (which should internally contain references to multiple featureStats dataframes, for example, the results of multiple differential expression tests).

...,
{
  "fileType": "comparativeFeatureStats.anndata.zarr",
  "url": "https://example.com/my_comparative_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "sampleType": "sample",
    "featureType": "gene"
  },
  "options": {
    // Path to the comparison metadata.
    "metadataPath": "uns/comparison_metadata",
    // Optionally, specify the name of a column containing the feature index.
    "indexColumn": "names",
    // Specify the column containing p-values.
    "pValueColumn": "pvals_adj",
    // Optionally, specify how the p-values have already been transformed.
    "pValueTransformation": "minuslog10",
    // Does the p-value column contain adjusted p-values?
    "pValueAdjusted": true,
    // Specify the column containing fold-change values.
    "foldChangeColumn": "logfoldchanges",
    // Optionally, specify how the fold-change values have already been tranformed.
    "foldChangeTransformation": "log2"
  }
},
...

comparativeFeatureSetStats.anndata.zarr​

Per-feature-set statistics that have been pre-computed and stored in the AnnData object. Rather than pointing to the location of the results directly, with this file type, we point to the comparison metadata location (which should internally contain references to multiple featureSetStats dataframes, for example, the results of multiple gene set enrichment tests).

...,
{
  "fileType": "comparativeFeatureSetStats.anndata.zarr",
  "url": "https://example.com/my_comparative_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "sampleType": "sample",
    "featureType": "gene"
  },
  "options": {
    // Path to the comparison metadata.
    "metadataPath": "uns/comparison_metadata",
    // Optionally, specify the name of a column containing the feature set index.
    "indexColumn": "pathway_name",
    // Specify the column containing ontology terms (CURIE strings).
    "termColumn": "pathway_term",
    // Specify the column containing p-values.
    "pValueColumn": "pvals_adj",
    // Does the p-value column contain adjusted p-values?
    "pValueAdjusted": true,
    // Optionally, what gene set library was used for testing and is specified in the metadata?
    "featureSetLibrary": "Reactome_2022"
  }
},
...

comparativeObsSetStats.anndata.zarr​

Per-observation-set statistics that have been pre-computed and stored in the AnnData object. Rather than pointing to the location of the results directly, with this file type, we point to the comparison metadata location (which should internally contain references to multiple obsSetStats dataframes, for example, the results of multiple cell type composition analyses).

...,
{
  "fileType": "comparativeObsSetStats.anndata.zarr",
  "url": "https://example.com/my_comparative_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "sampleType": "sample"
  },
  "options": {
    // Path to the comparison metadata.
    "metadataPath": "uns/comparison_metadata",
    // Optionally, specify the name of a column containing the obs set index.
    "indexColumn": "names",
    // Specify the column containing fold-change values.
    "foldChangeColumn": "logfoldchanges",
    // Optionally, specify how the fold-change values have already been tranformed.
    "foldChangeTransformation": "log2",
    // For scCODA results, this indicates the expected value for a new sample in absence of the covariate.
    "interceptExpectedSampleColumn": "interceptExpectedSample",
    // For scCODA results, this indicates the expected value for a new sample in presence of the covariate.
    "effectExpectedSampleColumn": "effectExpectedSample",
    // For scCODA results, this is a boolean column indicating whether a credible change was detected for the cell type.
    "isCredibleEffectColumn": "isCredibleEffect"
  }
},
...

anndata.zarr​

Defines an AnnData object that has been written to a Zarr store. This is a joint file type.

...,
{
  "fileType": "anndata.zarr",
  "url": "https://example.com/my_adata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    "obsPoints": {
      // Accepts the same options as obsPoints.anndata.zarr
      "path": "obsm/X_spatial"
    },
    "obsSpots": {
      // Accepts the same options as obsSpots.anndata.zarr
      "path": "obsm/X_spatial"
    },
    "obsSegmentations": {
      // Accepts the same options as obsSegmentations.anndata.zarr
      "path": "obsm/X_segmentations"
    },
    "obsLocations": {
      // Accepts the same options as obsLocations.anndata.zarr
      "path": "obsm/X_centroids"
    },
    "obsEmbedding": [
      {
        // Accepts a superset of the options from obsEmbedding.anndata.zarr
        // Should point to an array of (d1, d2) coordinate pairs, one coordinate pair per obs/cell.
        "path": "obsm/X_umap",
        // An embeddingType must be specified to distinguish between multiple embedding arrays.
        "embeddingType": "UMAP"
      },
      {
        "path": "obsm/X_pca",
        "dims": [4, 5],
        "embeddingType": "PCA"
      }
    ],
    "obsLabels": [
      {
        // Accepts a superset of the options from obsLabels.anndata.zarr
        "path": "obs/alt_cell_id",
        // An obsLabelsType must be specified to distinguish between multiple label columns.
        "obsLabelsType": "Alternate cell ID"
      }
    ],
    "obsSets": [
      // Accepts the same options as obsSets.anndata.zarr
      {
        "name": "Cell Type Annotations",
        "path": ["obs/cell_type_coarse", "obs/cell_type_fine"]
      }
    ],
    "obsFeatureMatrix": {
      // Accepts the same options as obsFeatureMatrix.anndata.zarr
      // Should point to the observation-by-feature matrix
      "path": "X"
    }
  }
},
...

MuData-Zarr​

MuData is the multi-modal analog of AnnData. A MuData object is a container data structure for multiple named AnnData objects. Like AnnData objects, MuData objects can be saved to Zarr format.

Note that MuData objects have both "global" and per-modality obs and var indices. In Vitessce, when loading an array from within a modality (i.e., with a path prefixed by mod/), the modality-specific indices will be used. In contrast, when loading a "global" array, the corresponding global indices will be used.

obsFeatureMatrix.mudata.zarr​

An observation-by-feature matrix with observations along the obs axis (rows) and features along the var axis (columns). For some rna modality, this would typically be stored in mdata.mod['rna'].X, but the "path" option allows pointing to any array within the MuData object.

The data types and sub-matrix information from obsFeatureMatrix.anndata.zarr apply.

...,
{
  "fileType": "obsFeatureMatrix.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    // Should point to an observation-by-feature matrix
    "path": "mod/rna/X"
  }
},
...

obsEmbedding.mudata.zarr​

A two-column array with entries along the obs axis. The two columns store 2D embedding coordinates. For example, the contents of mdata.mod['rna'].obsm['X_umap'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsEmbedding.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "embeddingType": "UMAP"
  },
  "options": {
    // Should point to an array of (d1, d2) coordinate pairs, one coordinate pair per obs/cell.
    "path": "mod/rna/obsm/X_umap",
    // Dimension indices are optional. By default, [0, 1].
    "dims": [0, 1]
  }
},
...

obsPoints.mudata.zarr​

A two-column array with entries along the obs axis. The two columns store (x, y) spatial coordinates. For example, the contents of mdata.mod['rna'].obsm['X_spatial'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsPoints.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to an array of (x, y) coordinate pairs, one coordinate pair per obs/cell.
    "path": "mod/rna/obs/X_spatial"
  }
},
...

obsSpots.mudata.zarr​

A two-column array with entries along the obs axis. The two columns store (x, y) spatial coordinates. For example, the contents of mdata.mod['rna'].obsm['X_spatial'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsSpots.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to an array of (x, y) coordinate pairs, one coordinate pair per obs/cell.
    "path": "mod/rna/obs/X_spatial"
  }
},
...

obsSets.mudata.zarr​

Maps each observation to membership in one or more sets. Typically used to assign cells to cell type labels or cell cluster IDs. To allow for multiple groups of sets to be be specified, options takes an array.

If a group of sets is organized as a flat list, then "path" points to a column containing string labels. Alternatively, if organized as a hierarchy, then "path" can point to an array of columns, progressing from coarser to finer labels.

For example, the contents of mdata.mod['rna'].obs might look like:

indexleidencell_type_coarsecell_type_finepred_cell_typepred_score
cell_11ImmuneB cellB cell0.81
cell_22ImmuneT cellT cell0.99
cell_32ImmuneT cellMacrophage0.21
cell_43NeuronExcitatory neuronInhibitory neuron0.25
..................
...,
{
  "fileType": "obsSets.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": [
    {
      "name": "Leiden Clustering",
      "path": "mod/rna/obs/leiden"
    },
    {
      "name": "Cell Type Annotations",
      "path": ["mod/rna/obs/cell_type_coarse", "mod/rna/obs/cell_type_fine"]
    },
    {
      "name": "Predicted Cell Types",
      "path": "mod/rna/obs/pred_cell_type",
      "scorePath": "mod/rna/obs/pred_score"
    }
  ]
},
...

obsSegmentations.mudata.zarr​

...,
{
  "fileType": "obsSegmentations.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to an array of polygon vertices, one polygon per obs/cell.
    "path": "mod/rna/obs/X_segmentations"
  }
},
...

obsLabels.mudata.zarr​

A column containing string labels along the obs axis. For example, the contents of mdata.mod['rna'].obs['alt_cell_id'] might look like:

index
cell_1     ATCGC
cell_2     TCGGC
cell_3     TTTCA
Name: alt_cell_id, dtype: object
...,
{
  "fileType": "obsLabels.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "obsLabelsType": "Alternate cell ID"
  },
  "options": {
    // Should point to a string column
    "path": "mod/rna/obs/alt_cell_ids"
  }
},
...

obsLocations.mudata.zarr​

A two-column array with entries along the obs axis. The two columns store (x, y) spatial coordinates. For example, the contents of mdata.mod['rna'].obsm['X_spatial'] might look like:

array([[ 3.1402664 , -7.1668797 ],
       [-3.105793  , -3.2035291 ],
       [ 6.1815314 ,  3.4141443 ],
       ...,
       [ 6.922351  , -6.529349  ],
       [ 4.714882  , -4.027811  ],
       [ 0.75445884, -4.2975116 ]], dtype=float32)
...,
{
  "fileType": "obsLocations.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to an array of (x, y) coordinate pairs, one coordinate pair per obs/cell.
    "path": "mod/rna/obs/X_spatial"
  }
},
...

featureLabels.mudata.zarr​

A column containing string labels along the var axis. For example, the contents of mdata.mod['rna'].var['gene_symbol'] might look like:

index
ENSG00000152128     TMEM163
ENSG00000153086     ACMSD
ENSG00000082258     CCNT2
ENSG00000176601     MAP3K19
ENSG00000115839     RAB3GAP1
Name: gene_symbol, dtype: object
...,
{
  "fileType": "featureLabels.mudata.zarr",
  "url": "https://example.com/my_mdata.zarr",
  "coordinationValues": {
    "featureType": "gene",
    "featureLabelsType": "Gene symbol"
  },
  "options": {
    // Should point to a string column
    "path": "mod/rna/var/gene_symbol"
  }
},
...

SpatialData​

SpatialData is a data structure for spatial omics data. It uses a Zarr-based on-disk format which is a container for AnnData-Zarr tables and OME-Zarr images.

The on-disk format is relatively stable but still in the early days, so we will be following any changes to the on-disk representation closely so that we can support the most up-to-date version in Vitessce. For example, support for multiple tables is currently under discussion, coordinate transformations use a proposed format that is not yet incorporated into OME-NGFF, and channel metadata is temporarily using a non-NGFF property.

SpatialData defines several spatial elements: points, shapes, labels, images, and tables. These can be mapped to Vitessce data types:

SpatialData SpatialElementVitessce DataType
pointsobsPoints
shapes (circles)obsSpots
shapes (polygons)obsSegmentations
labelsobsSegmentations
imagesimage
tablesobsFeatureMatrix
obsSets
obsLabels
obsEmbedding

obsSpots.spatialdata.zarr​

...,
{
  "fileType": "obsSpots.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to the table containing the circular shape geometries.
    "path": "shapes/some_region_shapes",
    // Should point to the table which annotates the specified shapes. Optional.
    "tablePath": "tables/table",
    // Region value to use for filtering the rows of the table.
    "region": "some_region_shapes"
  }
},
...

obsPoints.spatialdata.zarr​

See our documentation on how to store point data to enable efficient tiled loading when using SpatialData.

...,
{
  "fileType": "obsPoints.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to the table containing the point coordinates.
    "path": "points/some_region_points",
    // Should point to the table which annotates the specified shapes. Optional.
    "tablePath": "tables/table",
    // Region value to use for filtering the rows of the table.
    "region": "some_region_points"
  }
},
...

shapes.spatialdata.zarr​

...,
{
  "fileType": "shapes.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to the table containing the polygon shape geometries.
    "path": "shapes/some_region_shapes",
    // Should point to the table which annotates the specified shapes. Optional.
    "tablePath": "tables/table",
    // Region value to use for filtering the rows of the table.
    "region": "some_region_shapes"
  }
},
...

labels.spatialdata.zarr​

SpatialData label images represent segmentation bitmasks for observations.

...,
{
  "fileType": "labels.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "fileUid": "cell-bitmask",
    "obsType": "cell"
  },
  "options": {
    // Should point to a label image.
    "path": "labels/my_cell_bitmask"
  }
},
...

image.spatialdata.zarr​

...,
{
  "fileType": "image.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "fileUid": "histology-image"
  },
  "options": {
    // Should point to an image.
    "path": "images/some_image"
  }
},
...

obsFeatureMatrix.spatialdata.zarr​

...,
{
  "fileType": "obsFeatureMatrix.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Should point to a 2D array within the AnnData table object.
    "path": "tables/table/X"
  }
},
...

obsEmbedding.spatialdata.zarr​

...,
{
  "fileType": "obsEmbedding.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "embeddingType": "UMAP"
  },
  "options": {
    // Should point to an array of (d1, d2) coordinate pairs, one coordinate pair per obs/cell.
    "path": "obsm/X_umap",
    // Dimension indices are optional. By default, [0, 1].
    "dims": [0, 1]
  }
},
...

obsSets.spatialdata.zarr​

Maps each observation to membership in one or more sets. Typically used to assign cells to cell type labels or cell cluster IDs. To allow for multiple groups of sets to be be specified, options.obsSets takes an array.

If a group of sets is organized as a flat list, then "path" points to a column containing string labels. Alternatively, if organized as a hierarchy, then "path" can point to an array of columns, progressing from coarser to finer labels.

For example, the contents of sdata.table.obs might look like:

indexleidencell_type_coarsecell_type_finepred_cell_typepred_score
cell_11ImmuneB cellB cell0.81
cell_22ImmuneT cellT cell0.99
cell_32ImmuneT cellMacrophage0.21
cell_43NeuronExcitatory neuronInhibitory neuron0.25
..................
...,
{
  "fileType": "obsSets.spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    // Array of { name, path, ... } objects specifying columns containing set values.
    "obsSets": [
      {
        "name": "Leiden Clustering",
        "path": "tables/table/obs/leiden"
      },
      {
        "name": "Cell Type Annotations",
        "path": ["tables/table/obs/cell_type_coarse", "tables/table/obs/cell_type_fine"]
      },
      {
        "name": "Predicted Cell Types",
        "path": "tables/table/obs/pred_cell_type",
        "scorePath": "tables/table/obs/pred_score"
      }
    ],
    // Region value to filter the rows of the table. Optional.
    "region": "some_region",
    // Path to table containing the index that is aligned to the set columns. Optional.
    "tablePath": "tables/table"
  }
},
...

spatialdata.zarr​

Defines an SpatialData object that has been written to a Zarr store. This is a joint file type.

Note that while this options schema only supports a single image/obsSegmentations/etc., multiple spatialdata.zarr files (pointing to the same or different SpatialData objects) can be defined in a single list of files in the dataset configuration.

...,
{
  "fileType": "spatialdata.zarr",
  "url": "https://example.com/my_sdata.zarr",
  "coordinationValues": {
    "obsType": "cell",
    "featureType": "gene",
    "featureValueType": "expression"
  },
  "options": {
    "image": {
      // Accepts the same options as image.spatialdata.zarr
      "path": "images/visium_151673_full_image"
    },
    "obsSegmentations": {
      // Accepts the same options as {labels|shapes}.spatialdata.zarr
      "path": "labels/visium_151673_annotations"
    },
    "obsFeatureMatrix": {
      // Accepts the same options as obsFeatureMatrix.spatialdata.zarr
      "path": "tables/table/X"
    },
    "obsSpots": {
      // Accepts the same options as obsSpots.spatialdata.zarr
      "path": "shapes/visium_151673",
    },
    "obsSets": {
      // Accepts the same options as obsSets.spatialdata.zarr;
      // Similar to obsSets.anndata.zarr
      "obsSets": [
        {
          "name": "Cell Type Annotations",
          "path": ["tables/table/obs/cell_type_coarse", "tables/table/obs/cell_type_fine"]
        }
      ],
      "tablePath": "tables/table"
    },
    "obsEmbedding": [
      {
        // Should point to an array of dimensionality reduction coordinates;
        // Similar to obsEmbedding.anndata.zarr
        "path": "tables/table/obsm/X_umap",
        // An embeddingType must be specified to distinguish between multiple embedding arrays.
        "embeddingType": "UMAP"
      }
    ]
  }
},
...

JSON​

obsSets.json​

Storage of sets of observations in a tree data structure. If this tree has a uniform height within each top-level group then it may be more straightforward to use the obsSets.csv or obsSets.anndata.zarr file types. See the JSON schema and an example for reference.

...,
{
  "fileType": "obsSets.json",
  "url": "https://example.com/my_cell_sets.json",
  "coordinationValues": {
    "obsType": "cell"
  }
},
...

obsSegmentations.json​

Storage of per-observation segmentation polygons, where each polygon is represented as an array of vertices. File contents might look like:

{
  "cell_1": [
    [6668, 26182],
    [6668, 26296],
    [6873, 26501],
    [6932, 26501],
    [6955, 26478],
    [6955, 26260],
    [6838, 26143],
    [6707, 26143]
  ],
  "cell_2": [
    [5047, 44428],
    [5047, 44553],
    [5065, 44571],
    [5125, 44571],
    [5284, 44412],
    [5284, 44368],
    [5239, 44323],
    [5152, 44323]
  ],
  ...
}
...,
{
  "fileType": "obsSegmentations.json",
  "url": "https://example.com/my_cell_segmentations.json",
  "coordinationValues": {
    "obsType": "cell"
  }
},
...

obsSegmentations.raster.json​

Points to one or more segmentation bitmasks in OME-TIFF format. See the options JSON schema for reference. Note that for this file type, the top-level "url" property is not required (URLs are specified for each image in options.images[].url instead).

...,
{
  "fileType": "obsSegmentations.raster.json",
  "coordinationValues": {
    "obsType": "cell"
  },
  "options": {
    "renderLayers": ["My OME-TIFF Mask"],
    "schemaVersion": "0.0.2",
    "images": [
      {
        "name": "My OME-TIFF Mask",
        "url": "http://example.com/my_mask.ome.tif",
        "type": "ome-tiff"
      }
    ]
  }
},
...

obsSegmentations.ome-tiff​

Points to a label image ("bitmask") in OME-TIFF format. Pixel values are integers that correspond to segmented observations, with 0 representing background.

See the OME-TIFF Troubleshooting documentation for more information.

...,
{
  "fileType": "obsSegmentations.ome-tiff",
  "url": "https://example.com/my_cell_segmentations.ome.tif",
  "options": {
    // Optionlly, specify a path to an offsets.json file.
    // This is recommended to improve performance for large OME-TIFF files.
    "offsetsUrl": "https://example.com/my_cell_segmentations.offsets.json",
    // Optionally, specify coordinate transformations.
    "coordinateTransformations": [
      {
        "type": "scale",
        // Specify one value per dimension.
        // e.g., to scale 2x in X and Y
        // for an image with DimensionOrder "XYZCT":
        "scale": [2.0, 2.0, 1.0, 1.0, 1.0]
      },
    ],
    // Optionally, specify whether obsType values
    // for each segmentation channel should be auto-initialized to
    // the image channel names present within the OME-XML metadata.
    "obsTypesFromChannelNames": false
  }
},
...

image.ome-tiff​

Points to an image in OME-TIFF format.

If the OME-XML metadata contains PhysicalSizeX, PhysicalSizeXUnit, PhysicalSizeY, and PhysicalSizeYUnit, then the physical size will be used for scaling.

Optionally, options.coordinateTransformations can be defined, which will be interpreted according to the OME-NGFF v0.4 coordinateTransformations spec. The dimensions of these transformations must correspond to the DimensionOrder from OME-XML.

See the OME-TIFF Troubleshooting documentation for more information.

...,
{
  "fileType": "image.ome-tiff",
  "url": "https://example.com/my_image.ome.tif",
  "options": {
    // Optionlly, specify a path to an offsets.json file.
    // This is recommended to improve performance for large OME-TIFF files.
    "offsetsUrl": "https://example.com/my_image.offsets.json"
  }
},
...

obsSegmentations.ome-zarr​

Points to a label image ("bitmask") in OME-NGFF format. Pixel values are integers that correspond to segmented observations, with 0 representing background.

...,
{
  "fileType": "obsSegmentations.ome-zarr",
  "url": "https://example.com/my_cell_segmentations.ome.zarr",
  "options": {
    // Optionally, specify coordinate transformations.
    "coordinateTransformations": [
      {
        "type": "scale",
        // Specify one value per dimension.
        // e.g., to scale 2x in X and Y
        // for an image with DimensionOrder "XYZCT":
        "scale": [2.0, 2.0, 1.0, 1.0, 1.0]
      },
    ],
    // Optionally, specify whether obsType values
    // for each segmentation channel should be auto-initialized to
    // the image channel names present within the OME-XML metadata.
    "obsTypesFromChannelNames": false
  }
},
...

image.ome-zarr​

Points to an image in OME-NGFF format that has been saved to a Zarr store. See OME-NGFF data troubleshooting for more details.

Optionally, options.coordinateTransformations can be defined according to the OME-NGFF v0.4 coordinateTransformations spec (Zod schema). These will be applied after any coordinateTransformations contained within the Zarr store's OME-NGFF metadata.

...,
{
  "fileType": "image.ome-zarr",
  "url": "https://example.com/my_image.ome.zarr"
},
...

Example with coordinateTransformations provided via options:

...,
{
  "fileType": "image.ome-zarr",
  "url": "https://example.com/my_image.ome.zarr",
  "options": {
    "coordinateTransformations": [
      {
        "type": "translation",
        "translation": [0, 0, 1, 1],
      },
      {
        "type": "scale",
        "scale": [1, 0.5, 0.5, 0.5],
      },
    ],
  }
},
...

obsSegmentations.ng-precomputed​

The URL should point to "precomputed" multi-resolution chunked meshes. See the Neuroglancer documentation to learn about the precomputed multi-resolution mesh format. This fileType is intended to be used with the neuroglancer view type.

The fileType options value is used to construct the internal viewerState for the Neuroglancer view. The complete viewerState schema is available in the Neuroglancer documentation.

Note: Neuroglancer expects coordinates in the precomputed mesh format to be in nanometers (XYZ). See discussion on GitHub for more details.

...,
{
  "fileType": "obsSegmentations.ng-precomputed",
  "url": "https://example.com/my_meshes",
  "options": {
    // Dimensions map voxel steps to physical units along each axis.
    // Precomputed format expects nanometer (nm) units.
    // If your data are in meters, convert (e.g., 1e-9 m = 1 nm) before setting these.
    "dimensionX": 1,      // 1 nm
    "dimensionY": 1,      // 1 nm
    "dimensionZ": 1,      // 1 nm
    "dimensionUnit": 'nm',
  
    // Optional camera settings; defaults are used if omitted.
    "position": [49.5, 1000.5, 5209.5],
    "projectionScale": 1024,
    "projectionOrientation": [
      -0.636204183101654,
      -0.5028395652770996,
      0.5443811416625977,
      0.2145828753709793
    ],
  }
},
...

image.raster.json​

Points to one or more images in OME-TIFF or Bioformats-Zarr format. See the options JSON schema for reference. Note that for this file type, the top-level "url" property is not required (URLs are specified for each image in options.images[].url instead).

...,
{
  "fileType": "image.raster.json",
  "options": {
    "renderLayers": ["My OME-TIFF Image"],
    "schemaVersion": "0.0.2",
    "images": [
      {
        "name": "My OME-TIFF Image",
        "url": "http://example.com/my_image.ome.tif",
        "type": "ome-tiff",
        "metadata": {
          "transform": {
            // An optional transformation matrix
            // in column-major order.
            "matrix": [
              0.81915098, -0.57357901, 0, 3264.76514684,
              0.57357502, 0.819152, 0, 556.50440621,
              0, 0, 1, 0,
              0, 0, 0, 1
            ]
          }
        }
      }
    ]
  }
},
...

Example with a Zarr store:

...,
{
  "fileType": "image.raster.json",
  "options": {
    "schemaVersion": "0.0.2",
    "images": [
      {
        "name": "My Bioformats-Zarr Image",
        "url": "http://example.com/my_image.zarr",
        "type": "zarr",
        "metadata": {
          "dimensions": [
            {
              "field": "channel",
              "type": "nominal",
              "values": [
                "DAPI - Hoechst (nuclei)",
                "FITC - Laminin (basement membrane)",
                "Cy3 - Synaptopodin (glomerular)",
                "Cy5 - THP (thick limb)"
              ]
            },
            {
              "field": "y",
              "type": "quantitative",
              "values": null
            },
            {
              "field": "x",
              "type": "quantitative",
              "values": null
            }
          ],
          "isPyramid": true,
          "transform": {
            "translate": {
              "y": 0,
              "x": 0
            },
            "scale": 1
          }
        }
      }
    ]
  }
},
...

genomic-profiles.zarr​

Points to a Zarr store containing cluster-level quantitative genomic profiles.

...,
{
  "fileType": "genomic-profiles.zarr",
  "url": "https://example.com/my_genomic_profiles.zarr"
},
...