Skip to main content

View Configs via JSON

The Vitessce view config defines datasets (and the URLs to their associated data files) and views that will be used to visualize and interact with the data. The view config also stores the coordination space (i.e., the state of the views) and defines which views and properties are coordinated.

We realise that having to construct a view config adds friction, for instance preventing quick visualization of an image or AnnData object. This is why for some file formats, Vitessce can generate a valid view config, using URLs to your datasets (see Data Preparation). For more information, see the automatic configuration page.

Required properties​

note

The full view config JSON schema can be found here.

name​

  • Type: string

A name for the view config. Although this field is required, you are welcome to use the empty string.

version​

  • Type: string

The view config schema version. The documentation pages here are based on the latest version.

ValueNotes
1.0.0Support for the coordination space was added in this version.
1.0.1The spatialLayers coordination type was split into spatialRasterLayers, spatialCellsLayer, spatialMoleculesLayer, and spatialNeighborhoodsLayer in this version.
1.0.2Auto-detection of 3D images was added in this version.
1.0.3Channel sliders for RGB images was added in this version.
1.0.4Adds the coordination types embeddingCellOpacity, embeddingCellRadiusMode, and embeddingCellOpacityMode.
1.0.5Adds support for providing an array of columns (rather than a single column) for the value of the setName property within options array items for the anndata-cell-sets.zarr file type (to specify a cell set hierarcy).
1.0.6The scoreName property within the options array items for the anndata-cell-sets.zarr file type was added in this version.
1.0.7The geneAlias option for the anndata-expression-matrix.zarr file type was added in this version.
1.0.8Support for multi-dataset views and dataset-specific coordination scope mappings was added in this version.
1.0.9Support for plugin coordination types was added in this version.
1.0.10Support for the optional layout[].uid field.
1.0.11Coordination type names were changed in this version to move towards support for feature-observation matrices (FOM).
1.0.12Made the datasets[].files[].type field optional.
1.0.13Support for the property datasets[].files[].coordinationValues.
1.0.14Adds the coordination types gatingFeatureSelectionX, gatingFeatureSelectionY, and featureValueTransformCoefficient.
1.0.15View type names were changed in this version to move towards support for feature-observation matrices (FOM).
1.0.16Support for coordinationScopesBy for multiple per-coordination-type coordination scopes.

initStrategy​

  • Type: string

The coordination space initialization strategy. The initialization strategy determines how missing coordination objects and coordination scope mappings are initially filled in.

ValueNotes
autoRecommended. This strategy will allow you to omit some or all coordination scope mappings.
noneUse this strategy if you would like to define all coordination scope mappings yourself.
note

If you find yourself following certain patterns when initializing coordination spaces manually, please let us know so that we may work with you to implement this pattern as a supported strategy.

datasets​

  • Type: object[]

The datasets array stores a list of dataset objects. Each dataset object must contain a unique ID uid, a list of file objects files, and an optional name.

uid​

  • Type: string

A unique ID for the dataset. Required.

name​

  • Type: string

A human-readable name for the dataset. Optional.

files​

  • Type: object[]

The files array stores a list of file objects for a dataset. File objects must contain a fileType. All file types require a url string (with the exception of image.raster.json and obsSegmentations.raster.json). We don't associate any semantics with URL strings.

For more information about data types and file types, please visit our Data Types and File Types documentation page.

...,
"datasets": [
    {
        "uid": "my-dataset",
        "name": "My amazing dataset",
        "files": [
            {
                "fileType": "obsEmbedding.csv",
                "url": "http://example.com/umap.csv",
                "coordinationValues": {
                    "obsType": "cell",
                    "embeddingType": "UMAP"
                },
                "options": {
                    ...
                }
            },
            {
                "fileType": "obsEmbedding.csv",
                "url": "http://example.com/pca.csv",
                "coordinationValues": {
                    "obsType": "cell",
                    "embeddingType": "PCA"
                },
                "options": {
                    ...
                }
            },
            {
                "fileType": "image.ome-zarr",
                "url": "http://example.com/my_image.zarr"
            }
        ]
    }
],
...

layout​

  • Type: object[]

The layout property defines which visualization (and controller) components will be rendered, how they will be arranged on the screen, and optionally how they will map onto coordination scopes. Each layout object represents one "component" or "view", and must contain a component name component, width w and height h, and horizontal position x and vertical position y. Components are arranged in a grid with 12 columns and a dynamic number of rows. Optionally, each component may contain the properties uid, coordinationScopes, and props.

For more information about the available view types and coordination types, please visit the View Types and Coordination Types documentation pages.

...,
"layout": [
    {
        "component": "scatterplot",
        "x": 0, "y": 0, "w": 6, "h": 12,
        "coordinationScopes": {
            "dataset": "D1",
            "embeddingZoom": "EZ1",
            "embeddingType": "ET1"
        }
    },
    {
        "component": "scatterplot",
        "x": 6, "y": 0, "w": 6, "h": 12,
        "coordinationScopes": {
            "dataset": "D1",
            "embeddingZoom": "EZ2",
            "embeddingType": "ET2"
        }
    }
],
...

Optional properties​

coordinationSpace​

  • Type: object

The coordination space stores the values associated with each coordination object. It may be helpful to recall that the coordination space is analogous to computer memory which stores values of variables, and the coordination scope names are analogous to references to different locations in memory.

The keys of each object (at the first level) in the coordination space represent coordination types. The keys of each coordination type object represent coordination scope names. The types of values that each coordination scope can take can be as simple as a single number or as complex as an array or object, and depend on the types of values supported by its coordination type.

...,
"coordinationSpace": {
    "dataset": {
        "D1": "my-dataset"
    },
    "embeddingZoom": {
        "EZ1": 2,
        "EZ2": 20
    },
    "embeddingType": {
        "ET1": "UMAP",
        "ET2": "PCA"
    }
},
...

When the coordination space is entirely or partially omitted from the view config, initStrategy determines how the missing parts will be initialized.

description​

  • Type: string

An optional description for the view config.

uid​

  • Type: string

A unique ID for the config. Optional.

Intended to be used in situations where <Vitessce/> is used as a controlled component (i.e., a parent component is the source of truth for the config prop and likely also uses the onConfigChange prop). For example, if a change in config.uid is detected, the configuration will be re-validated (which might not occur on other changes to config for performance reasons).

Note that this config.uid property has a different function from the uid prop on the <Vitessce/> component.

tip

Vitessce uses a JSON-based view configuration internally. However, we provide language-specific object-oriented view config APIs as alternative ways to construct configurations: