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.

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"]
  }
},
...

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"
  }
},
...

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]
  }
},
...

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"
  }
},
...

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"
  }
},
...

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"
  }
},
...

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": {
    "obsLocations": {
      // Accepts the same options as obsLocations.anndata.zarr
      "path": "obsm/X_centroids"
    },
    "obsSegmentations": {
      // Accepts the same options as obsSegmentations.anndata.zarr
      "path": "obsm/X_segmentations"
    },
    "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"
    }
  }
},
...

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"
      }
    ]
  }
},
...

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.

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

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"
},
...

Other File Formats​

Other file formats must be converted to one or more of the file types listed above prior to being used with Vitessce. Here we provide tips for conversion from common single-cell file formats.

AnnData as h5ad​

Convert to Zarr​

Use AnnData's read_h5ad function to load the file as an AnnData object, then use the .write_zarr function to convert to a Zarr store. 

from anndata import read_h5ad
import zarr

adata = read_h5ad('path/to/my_dataset.h5ad')
adata.write_zarr('my_store.zarr')

Converted outputs can be used with the AnnData as Zarr family of native file types.

note

The ids in the obs part of the AnnData store must match the other data files with which you wish to coordinate outside the AnnData store. For example, if you have a bitmask that you wish to use with an AnnData store, the ids in obs need to be the very integers from each segmentation the bitmask.

Use or Store a subset of X​

When the full expression matrix adata.X is large, there may be performance costs if Vitessce tries to load the full matrix for visualization, whether it be a heatmap or just loading genes to overlay on a spatial or scatterplot view. To offset this there are two things you can do:

  1. Use CSC format or chunk the zarr store efficiently (the later is recommended at the moment, see below) so that the UI remains responsive when selecting a gene to load into the client. Every time a gene is selected (or the heatmap is loaded), the client will use Zarr to fetch all the "cell x gene" information needed for rendering - however, a poor chunking strategy can result in too much data be loaded (and then not used). To remedy this, we recommend passing in the chunk_size argument to write_zarr so that the data is chunked in a manner that allows remote sources (like browsers) to fetch only the genes (and all cells) necessary for efficient display - to this end the chunk size is usually something like [num_cells, small_number] so every chunk contains all the cells, but only a few genes. That way, when you select a gene, only a small chunk of data is fetched for rendering and little is wasted. Ideally, at most one small request is made for every selection. You are welcome to try different chunking strategies as you see fit though!
  2. If only interested in a subset of the expression matrix for a heatmap, a filter (matrixGeneFilter in the view config) for the matrix can be stored as a boolean array in var. In this case, it is the highly_variable key from the sc.pp.highly_variable_genes call below. This will not alter the genes displayed in the Genes view (use geneFilter for that in the view config).
import scanpy as sc
from anndata import read_h5ad
import zarr

adata = read_h5ad('path/to/my_dataset.h5ad')

# Adds the `highly_variable` key to `var`
sc.pp.highly_variable_genes(adata, n_top_genes=200)
# If the matrix is sparse, it's best for performance to
# use non-sparse formats + chunking to keep the UI responsive.
# In the future, we should be able to use CSC sparse data natively
# and get equal performance with chunking:
# https://github.com/theislab/anndata/issues/524 
# but for now, it is still not as good (although not unusable).
if isinstance(adata.X, sparse.spmatrix):
    adata.X = adata.X.todense() # Or adata.X.tocsc() if you need to.
adata.write_zarr(zarr_path, [adata.shape[0], VAR_CHUNK_SIZE])  # VAR_CHUNK_SIZE should be something small like 10

Alternatively, a smaller matrix can be stored as multi-dimensional observation array in adata.obsm and used in conjunction with the geneFilter part of the view config.

sc.pp.highly_variable_genes(adata, n_top_genes=200)
adata.obsm['X_top_200_genes'] = adata[:, adata.var['highly_variable']].X.copy()
adata.write_zarr('my_store.zarr')

Converted outputs can be used with the AnnData as Zarr family of native file types. Both dense and sparse expression matrices are supported.

Loom​

Convert to Zarr via AnnData​

Use AnnData's read_loom function to load the Loom file as an AnnData object, then use the .write_zarr function to convert to a Zarr store. 

from anndata import read_loom

adata = read_loom(
  'path/to/my_dataset.loom',
  obsm_names={ "tSNE": ["_tSNE_1", "_tSNE_2"], "spatial": ["X", "Y"] }
)
adata.write_zarr('my_store.zarr')

Converted outputs can be used with the AnnData as Zarr family of native file types.

Seurat​

The Vitessce R package can be used to convert Seurat objects to the cells.json and cell-sets.json file types.

SnapATAC​

The Vitessce Python package can be used to convert SnapATAC outputs to the genomic-profiles.zarr, cells.json, and cell-sets.json file types.

Proprietary Image Formats​

The Bio-Formats suite of tools can be used to convert from proprietary image formats to one of the open standard OME file formats supported by Vitessce.

tip

The Data Preparation section of the Viv documentation is a helpful resource for learning about converting to OME formats.

Conversion to OME-TIFF​

OME-TIFF images are supported via the image.raster.json file type.

Conversion to OME-NGFF​

OME-NGFF images saved as Zarr stores are supported via the image.ome-zarr file type.

tip

The ome-zarr Python package can be used to read the metadata of OME-NGFF images.