View config API

The VitessceConfig class provides functionality for creating view configs using a pythonic syntax, with support for exporting to dict or JSON format.

vitessce.config

class vitessce.config.VitessceConfig(name=None, description=None)[source]

A class to represent a Vitessce view config.

Construct a Vitessce view config object.

Parameters
  • name (str) – A name for the view config. Optional.

  • description (str) – A description for the view config. Optional.

from vitessce import VitessceConfig

vc = VitessceConfig(name='My Config')
add_coordination(*c_types)[source]

Add scope(s) for new coordination type(s) to the config.

Parameters

*c_types (str or vitessce.constants.CoordinationType) – A variable number of coordination types.

Returns

The instances for the new scope objects corresponding to each coordination type. These can be linked to views via the VitessceConfigView.use_coordination() method.

Return type

list[VitessceConfigCoordinationScope]

from vitessce import VitessceConfig, Component as cm, CoordinationType as ct

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
zoom_scope, x_scope, y_scope = vc.add_coordination(
    ct.SPATIAL_ZOOM,
    ct.SPATIAL_TARGET_X,
    ct.SPATIAL_TARGET_Y,
)
v1.use_coordination(zoom_scope, x_scope, y_scope)
v2.use_coordination(zoom_scope, x_scope, y_scope)
zoom_scope.set_value(2)
x_scope.set_value(0)
y_scope.set_value(0)
add_dataset(name='', uid=None)[source]

Add a dataset to the config.

Parameters
  • name (str) – A name for this dataset.

  • uid (str) – A unique identifier for this dataset. Optional. If None, will be automatically generated.

Returns

The instance for the new dataset.

Return type

VitessceConfigDataset

from vitessce import VitessceConfig, DataType as dt, FileType as ft

vc = VitessceConfig(name='My Config')
my_dataset = (
    vc.add_dataset(name='My Dataset')
    .add_file(
        url="http://example.com/cells.json",
        data_type=dt.CELLS,
        file_type=ft.CELLS_JSON,
    )
)
add_view(dataset, component, x=0, y=0, w=1, h=1, mapping=None)[source]

Add a view to the config.

Parameters
  • dataset (VitessceConfigDataset) – A dataset instance to be used for the data visualized in this view.

  • component (str or vitessce.constants.Component) – A component name, either as a string or using the Component enum values.

  • mapping (str) – An optional convenience parameter for setting the EMBEDDING_TYPE coordination scope value. This parameter is only applicable to the SCATTERPLOT component.

  • x (int) – The horizontal position of the view. Must be an integer between 0 and 11. Optional. This will be ignored if you call the layout method of this class using VitessceConfigViewHConcat and VitessceConfigViewVConcat objects.

  • y (int) – The vertical position of the view. Must be an integer between 0 and 11. Optional. This will be ignored if you call the layout method of this class using VitessceConfigViewHConcat and VitessceConfigViewVConcat objects.

  • w (int) – The width of the view. Must be an integer between 1 and 12. Optional. This will be ignored if you call the layout method of this class using VitessceConfigViewHConcat and VitessceConfigViewVConcat objects.

  • h (int) – The height of the view. Must be an integer between 1 and 12. Optional. This will be ignored if you call the layout method of this class using VitessceConfigViewHConcat and VitessceConfigViewVConcat objects.

Returns

The instance for the new view.

Return type

VitessceConfigView

from vitessce import VitessceConfig, Component as cm

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SCATTERPLOT, mapping="X_umap")
export(to, *args, **kwargs)[source]

Export this config’s data objects to the local file system or a cloud storage system and get the resulting view config.

Parameters
  • to (str) – The export destination. Valid values include “S3” and “files”.

  • **kwargs – Keyword arguments to pass to the export function.

Returns

The config as a dict, with URLs for the bucket filled in.

Return type

dict

from vitessce import VitessceConfig, Component as cm, CoordinationType as ct

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(v1)

config_dict = vc.export(to="S3")
static from_dict(config)[source]

Helper function to construct a Vitessce view config object from an existing config.

Parameters

config (dict) – An existing Vitessce view config as a dict to allow manipulation through the VitessceConfig API.

Returns

The config instance.

Return type

VitessceConfig

from vitessce import VitessceConfig

vc = VitessceConfig.from_dict(my_existing_config)
static from_object(obj, name=None, description=None)[source]

Helper function to automatically construct a Vitessce view config object from a single-cell dataset object. Particularly helpful when using the VitessceWidget Jupyter widget.

Parameters

obj (anndata.AnnData or loompy.LoomConnection or zarr.Store) – A single-cell dataset in the format of a commonly-used single-cell or imaging data analysis package.

Returns

The config instance.

Return type

VitessceConfig

from vitessce import VitessceConfig

vc = VitessceConfig.from_object(my_scanpy_object)
get_dataset(uid)[source]

Get a dataset associated with this configuration.

Parameters

uid (str) – The unique identifier for the dataset of interest.

Returns

The dataset object.

Return type

VitessceConfigDataset or None

get_datasets()[source]

Get the datasets associated with this configuration.

Returns

The list of dataset objects.

Return type

list of VitessceConfigDataset

get_routes()[source]

Convert the routes for this view config from the datasets.

Returns

A list of server routes.

Return type

list[starlette.routing.Route]

layout(view_concat)[source]

Create a multi-view layout based on (potentially recursive) view concatenations.

Parameters

view_concat (VitessceConfigViewHConcat or VitessceConfigViewVConcat or VitessceConfigView) – Views arranged by concatenating vertically or horizontally. Alternatively, a single view can be passed.

Returns

Self, to allow chaining.

Return type

VitessceConfig

from vitessce import VitessceConfig, Component as cm, hconcat, vconcat

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
v3 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(hconcat(v1, vconcat(v2, v3)))
from vitessce import VitessceConfig, Component as cm

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
v3 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(v1 | (v2 / v3)) # * magic * (alternative syntax)

A convenience function for setting up new coordination scopes across a set of views.

Parameters
  • views (list of VitessceConfigView) – views An array of view objects to link together.

  • c_types (list of str or list of vitessce.constants.CoordinationType) – The coordination types on which to coordinate the views.

  • c_values (list) – Initial values corresponding to each coordination type. Should have the same length as the c_types array. Optional.

Returns

Self, to allow chaining.

Return type

VitessceConfig

to_dict(base_url=None)[source]

Convert the view config instance to a dict object.

Parameters

base_url (str) – Optional parameter for non-remote data to specify the url from which the data will be served.

Returns

The view config as a dict. Useful for serializing to JSON.

Return type

dict

web_app(**kwargs)[source]

Launch the http://vitessce.io web app using this config.

Parameters
  • theme (str) – The theme name, either “light” or “dark”. By default, “auto”, which selects light or dark based on operating system preferences.

  • port (int) – The port to use when serving data objects on localhost. By default, 8000.

  • base_url (str or None) – If the web app is being accessed remotely (i.e. the data is being served from a remote machine), specify the base URL here. If serving and accessing the data on the same machine, keep as None to use a localhost URL.

  • open (bool) – Should the browser be opened to the web app URL? By default, True.

Returns

The URL of the web app (containing the Vitessce configuration as URL-encoded JSON).

Return type

str

from vitessce import VitessceConfig, Component as cm, CoordinationType as ct

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(v1)
vc.web_app()
widget(**kwargs)[source]

Instantiate a VitessceWidget object based on this config.

Parameters
  • theme (str) – The theme name, either “light” or “dark”. By default, “auto”, which selects light or dark based on operating system preferences.

  • height (int) – The height of the widget, in pixels. By default, 600.

  • port (int) – The port to use when serving data objects on localhost. By default, 8000.

  • proxy (bool) – Is this widget being served through a proxy, for example with a cloud notebook (e.g. Binder)?

Returns

The Jupyter widget.

Return type

VitessceWidget

from vitessce import VitessceConfig, Component as cm, CoordinationType as ct

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(v1)
vw = vc.widget()
vw
class vitessce.config.VitessceConfigCoordinationScope(c_type, c_scope)[source]

A class to represent a coordination scope in the Vitessce view config coordination space.

Not meant to be instantiated directly, but instead created and returned by the VitessceConfig.add_coordination() method.

Parameters
  • c_type (str) – The coordination type for this coordination scope.

  • c_scope (str) – The coordination scope name.

set_value(c_value)[source]

Set the value of the coordination scope.

Parameters

c_value (any) – The coordination value to be set. Can be any value that is valid for the coordination type. Must be serializable to JSON.

Returns

Self, to allow chaining.

Return type

VitessceConfigCoordinationScope

from vitessce import VitessceConfig, Component as cm, CoordinationType as ct

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
zoom_scope, x_scope, y_scope = vc.add_coordination(
    ct.SPATIAL_ZOOM,
    ct.SPATIAL_TARGET_X,
    ct.SPATIAL_TARGET_Y,
)
v1.use_coordination(zoom_scope, x_scope, y_scope)
v2.use_coordination(zoom_scope, x_scope, y_scope)
zoom_scope.set_value(2)
x_scope.set_value(0)
y_scope.set_value(0)
class vitessce.config.VitessceConfigDataset(uid, name)[source]

A class to represent a dataset (i.e. list of files containing common biological entities) in the Vitessce view config.

Not meant to be instantiated directly, but instead created and returned by the VitessceConfig.add_dataset() method.

Parameters
  • uid (str) – A unique identifier for this dataset.

  • name (str) – A name for this dataset.

add_file(url, data_type, file_type, options=None)[source]

Add a new file definition to this dataset instance.

Parameters
  • url (str) – The URL for the file, pointing to either a local or remote location.

  • data_type (str or vitessce.constants.DataType) – The type of data stored in the file. Must be compatible with the specified file type.

  • file_type (str or vitessce.constants.FileType) – The file type. Must be compatible with the specified data type.

Returns

Self, to allow function chaining.

Return type

VitessceConfigDataset

from vitessce import VitessceConfig, DataType as dt, FileType as ft

vc = VitessceConfig(name='My Config')
my_dataset = (
    vc.add_dataset(name='My Dataset')
    .add_file(
        url="http://example.com/cells.json",
        data_type=dt.CELLS,
        file_type=ft.CELLS_JSON,
    )
)
add_object(obj)[source]

Add a data object to this dataset instance.

Parameters

obj (anndata.AnnData or loompy.LoomConnection or zarr.Store) – A data object that can be served locally or uploaded to a remote storage provider.

Returns

Self, to allow function chaining.

Return type

VitessceConfigDataset

get_uid()[source]

Get the uid value for this dataset.

Returns

The uid.

Return type

str

class vitessce.config.VitessceConfigDatasetFile(url, data_type, file_type, options)[source]

A class to represent a file (described by a URL, data type, and file type) in a Vitessce view config dataset.

Not meant to be instantiated directly, but instead created and returned by the VitessceConfigDataset.add_file() method.

Parameters
  • url (str) – A URL to this file. Can be a localhost URL or a remote URL.

  • data_type (str) – A data type.

  • file_type (str) – A file type.

class vitessce.config.VitessceConfigView(component, coordination_scopes, x, y, w, h)[source]

A class to represent a view (i.e. visualization component) in the Vitessce view config layout.

Not meant to be instantiated directly, but instead created and returned by the VitessceConfig.add_view() method.

Parameters
  • component (str) – The name of the component used for this view.

  • coordination_scopes (dict) – A mapping of coordination types to coordination scopes.

  • x (int) – An x-coordinate for this view in the grid.

  • y (int) – A y-coordinate for this view in the grid.

  • w (int) – A width for this view in the grid.

  • h (int) – A height for this view in the grid.

use_coordination(*c_scopes)[source]

Attach a coordination scope to this view instance. All views using the same coordination scope for a particular coordination type will effectively be linked together.

Parameters

*c_scopes (VitessceConfigCoordinationScope) – A variable number of coordination scope instances can be passed.

Returns

Self, to allow chaining.

Return type

VitessceConfigView

from vitessce import VitessceConfig, Component as cm, CoordinationType as ct

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
zoom_scope, x_scope, y_scope = vc.add_coordination(
    ct.SPATIAL_ZOOM,
    ct.SPATIAL_TARGET_X,
    ct.SPATIAL_TARGET_Y,
)
v1.use_coordination(zoom_scope, x_scope, y_scope)
v2.use_coordination(zoom_scope, x_scope, y_scope)
zoom_scope.set_value(2)
x_scope.set_value(0)
y_scope.set_value(0)
class vitessce.config.VitessceConfigViewHConcat(views)[source]

A class to represent a horizontal concatenation of view instances.

Not meant to be instantiated directly, but instead created and returned by the hconcat helper function.

class vitessce.config.VitessceConfigViewVConcat(views)[source]

A class to represent a vertical concatenation of view instances.

Not meant to be instantiated directly, but instead created and returned by the vconcat helper function.

vitessce.config.hconcat(*views)[source]

A helper function to create a VitessceConfigViewHConcat instance.

Parameters

*views (VitessceConfigView or VitessceConfigViewVConcat or VitessceConfigViewHConcat) – A variable number of views to concatenate horizontally.

Returns

The concatenated view instance.

Return type

VitessceConfigViewHConcat

from vitessce import VitessceConfig, Component as cm, hconcat, vconcat

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
v3 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(hconcat(v1, vconcat(v2, v3)))
vitessce.config.vconcat(*views)[source]

A helper function to create a VitessceConfigViewVConcat instance.

Parameters

*views (VitessceConfigView or VitessceConfigViewVConcat or VitessceConfigViewHConcat) – A variable number of views to concatenate vertically.

Returns

The concatenated view instance.

Return type

VitessceConfigViewVConcat

from vitessce import VitessceConfig, Component as cm, hconcat, vconcat

vc = VitessceConfig()
my_dataset = vc.add_dataset(name='My Dataset')
v1 = vc.add_view(my_dataset, cm.SPATIAL)
v2 = vc.add_view(my_dataset, cm.SPATIAL)
v3 = vc.add_view(my_dataset, cm.SPATIAL)
vc.layout(hconcat(v1, vconcat(v2, v3)))

vitessce.constants

class vitessce.constants.Component(value)[source]

An enum type representing a view type in the visualization layout.

CELL_SETS = 'cellSets'[source]
CELL_SET_EXPRESSION = 'cellSetExpression'[source]
CELL_SET_SIZES = 'cellSetSizes'[source]
DESCRIPTION = 'description'[source]
GENES = 'genes'[source]
GENOMIC_PROFILES = 'genomicProfiles'[source]
HEATMAP = 'heatmap'[source]
LAYER_CONTROLLER = 'layerController'[source]
SCATTERPLOT = 'scatterplot'[source]
SPATIAL = 'spatial'[source]
STATUS = 'status'[source]
class vitessce.constants.CoordinationType(value)[source]

An enum type representing a coordination type in the Vitessce coordination model. The term coordination type refers to a parameter to be coordinated, and its programming-language-like type. For example, the SPATIAL_ZOOM coordination type represents a coordination of the zoom level of a spatial view, which can take a float value.

ADDITIONAL_CELL_SETS = 'additionalCellSets'[source]
CELL_COLOR_ENCODING = 'cellColorEncoding'[source]
CELL_FILTER = 'cellFilter'[source]
CELL_HIGHLIGHT = 'cellHighlight'[source]
CELL_SET_COLOR = 'cellSetColor'[source]
CELL_SET_HIGHLIGHT = 'cellSetHighlight'[source]
CELL_SET_SELECTION = 'cellSetSelection'[source]
DATASET = 'dataset'[source]
EMBEDDING_CELL_OPACITY = 'embeddingCellOpacity'[source]
EMBEDDING_CELL_OPACITY_MODE = 'embeddingCellOpacityMode'[source]
EMBEDDING_CELL_RADIUS = 'embeddingCellRadius'[source]
EMBEDDING_CELL_RADIUS_MODE = 'embeddingCellRadiusMode'[source]
EMBEDDING_ROTATION = 'embeddingRotation'[source]
EMBEDDING_TARGET_X = 'embeddingTargetX'[source]
EMBEDDING_TARGET_Y = 'embeddingTargetY'[source]
EMBEDDING_TARGET_Z = 'embeddingTargetZ'[source]
EMBEDDING_TYPE = 'embeddingType'[source]
EMBEDDING_ZOOM = 'embeddingZoom'[source]
GENE_EXPRESSION_COLORMAP = 'geneExpressionColormap'[source]
GENE_EXPRESSION_COLORMAP_RANGE = 'geneExpressionColormapRange'[source]
GENE_FILTER = 'geneFilter'[source]
GENE_HIGHLIGHT = 'geneHighlight'[source]
GENOMIC_TARGET_X = 'genomicTargetX'[source]
GENOMIC_TARGET_Y = 'genomicTargetY'[source]
GENOMIC_ZOOM_X = 'genomicZoomX'[source]
GENOMIC_ZOOM_Y = 'genomicZoomY'[source]
HEATMAP_TARGET_X = 'heatmapTargetX'[source]
HEATMAP_TARGET_Y = 'heatmapTargetY'[source]
HEATMAP_ZOOM_X = 'heatmapZoomX'[source]
HEATMAP_ZOOM_Y = 'heatmapZoomY'[source]
SPATIAL_AXIS_FIXED = 'spatialAxisFixed'[source]
SPATIAL_CELLS_LAYER = 'spatialCellsLayer'[source]
SPATIAL_MOLECULES_LAYER = 'spatialMoleculesLayer'[source]
SPATIAL_NEIGHBORHOODS_LAYER = 'spatialNeighborhoodsLayer'[source]
SPATIAL_ORBIT_AXIS = 'spatialOrbitAxis'[source]
SPATIAL_RASTER_LAYERS = 'spatialRasterLayers'[source]
SPATIAL_ROTATION_ORBIT = 'spatialRotationOrbit'[source]
SPATIAL_ROTATION_X = 'spatialRotationX'[source]
SPATIAL_ROTATION_Y = 'spatialRotationY'[source]
SPATIAL_ROTATION_Z = 'spatialRotationZ'[source]
SPATIAL_TARGET_X = 'spatialTargetX'[source]
SPATIAL_TARGET_Y = 'spatialTargetY'[source]
SPATIAL_TARGET_Z = 'spatialTargetZ'[source]
SPATIAL_ZOOM = 'spatialZoom'[source]
class vitessce.constants.DataType(value)[source]

An enum type representing the type of data contained in a file.

CELLS = 'cells'[source]
CELL_SETS = 'cell-sets'[source]
EXPRESSION_MATRIX = 'expression-matrix'[source]
GENOMIC_PROFILES = 'genomic-profiles'[source]
MOLECULES = 'molecules'[source]
NEIGHBORHOODS = 'neighborhoods'[source]
RASTER = 'raster'[source]
class vitessce.constants.FileType(value)[source]

An enum type representing the file format or schema to which a file conforms.

ANNDATA_CELLS_ZARR = 'anndata-cells.zarr'[source]
ANNDATA_CELL_SETS_ZARR = 'anndata-cell-sets.zarr'[source]
ANNDATA_EXPRESSION_MATRIX_ZARR = 'anndata-expression-matrix.zarr'[source]
CELLS_JSON = 'cells.json'[source]
CELL_SETS_JSON = 'cell-sets.json'[source]
CLUSTERS_JSON = 'clusters.json'[source]
EXPRESSION_MATRIX_ZARR = 'expression-matrix.zarr'[source]
GENES_JSON = 'genes.json'[source]
GENOMIC_PROFILES_ZARR = 'genomic-profiles.zarr'[source]
MOLECULES_JSON = 'molecules.json'[source]
NEIGHBORHOODS_JSON = 'neighborhoods.json'[source]
RASTER_JSON = 'raster.json'[source]