Data preparation APIs

Dataset wrapper classes provide functionality for adding in-memory or local data objects to datasets when rendering Vitessce as a Jupyter widget.

We provide default wrapper class implementations for data formats used by popular single-cell and imaging packages.

To write your own custom wrapper class, create a subclass of the AbstractWrapper class, implementing the getter functions for the data types that can be derived from your object.

vitessce.wrappers

class vitessce.wrappers.AbstractWrapper(**kwargs)[source]

An abstract class that can be extended when implementing custom dataset object wrapper classes.

TODO: Add some useful tests.

>>> assert True

Abstract constructor to be inherited by dataset wrapper classes.

Parameters

out_dir (str) – The path to a local directory used for data processing outputs. By default, uses a temp. directory.

auto_view_config(vc)[source]

Auto view configuration is intended to be used internally by the VitessceConfig.from_object method. Each subclass of AbstractWrapper may implement this method which takes in a VitessceConfig instance and modifies it by adding datasets, visualization components, and view coordinations. Implementations of this method may create an opinionated view config based on inferred use cases.

Parameters

vc (VitessceConfig) – The view config instance.

convert_and_save(dataset_uid, obj_i)[source]

Fill in the file_def_creators array. Each function added to this list should take in a base URL and generate a Vitessce file definition. If this wrapper is wrapping local data, then create routes and fill in the routes array. This method is void, should not return anything.

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

  • obj_i (int) – Within the dataset, the index of this data wrapper object.

get_file_defs(base_url)[source]

Obtain the file definitions for this wrapper class.

Parameters

base_url (str) – A base URL to prepend to relative URLs.

Returns

A list of file definitions.

Return type

list[dict]

get_out_dir_route(dataset_uid, obj_i)[source]

Obtain the Mount for the out_dir

Parameters
  • dataset_uid (str) – A dataset unique identifier for the Mount

  • obj_i (str) – A index of the current vitessce.wrappers.AbstractWrapper among all other wrappers in the view config

Returns

A starlette Mount of the the out_dir

Return type

list[starlette.routing.Mount]

get_routes()[source]

Obtain the routes that have been created for this wrapper class.

Returns

A list of server routes.

Return type

list[starlette.routing.Route]

class vitessce.wrappers.AnnDataWrapper(adata=None, adata_url=None, expression_matrix=None, matrix_gene_var_filter=None, gene_var_filter=None, cell_set_obs=None, cell_set_obs_names=None, spatial_centroid_obsm=None, spatial_polygon_obsm=None, mappings_obsm=None, mappings_obsm_names=None, mappings_obsm_dims=None, request_init=None, factors_obs=None, **kwargs)[source]

Wrap an AnnData object by creating an instance of the AnnDataWrapper class.

Parameters
  • adata (anndata.AnnData) – An AnnData object containing single-cell experiment data.

  • adata_url (str) – A remote url pointing to a zarr-backed AnnData store.

  • expression_matrix (str) – Location of the expression (cell x gene) matrix, like X or obsm/highly_variable_genes_subset

  • gene_var_filter (str) – A string like highly_variable (from var in the AnnData stored) used in conjunction with expression_matrix if expression_matrix points to a subset of X of the full var list.

  • matrix_gene_var_filter (str) – A string like highly_variable (from var in the AnnData stored) used in conjunction with expression_matrix if expression_matrix points to a subset of X of the full var list.

  • factors_obs (list[str]) – Column names like [‘top_marker_gene’, ‘sex’] for showing factors when cells are hovered over

  • cell_set_obs (list[str]) – Column names like [‘louvain’, ‘cellType’] for showing cell sets from obs

  • cell_set_obs_names (list[str]) – Names to display in place of those in cell_set_obs, like `[‘Louvain’, ‘Cell Type’]

  • spatial_centroid_obsm (str) – Column name in obsm that contains centroid coordinates for displaying centroids in the spatial viewer

  • spatial_polygon_obsm (str) – Column name in obsm that contains polygonal coordinates for displaying outlines in the spatial viewer

  • mappings_obsm (list[str]) – Column names like [‘X_umap’, ‘X_pca’] for showing scatterplots from obsm

  • mappings_obsm_names (list[str]) – Overriding names like `[‘UMAP’, ‘PCA’] for displaying above scatterplots

  • mappings_obsm_dims (list[str]) – Dimensions along which to get data for the scatterplot, like [[0, 1], [4, 5]] where [0, 1] is just the normal x and y but [4, 5] could be comparing the third and fourth principal components, for example.

  • request_init (dict) – options to be passed along with every fetch request from the browser, like { “header”: { “Authorization”: “Bearer dsfjalsdfa1431” } }

  • **kwargs – Keyword arguments inherited from AbstractWrapper

auto_view_config(vc)[source]

Auto view configuration is intended to be used internally by the VitessceConfig.from_object method. Each subclass of AbstractWrapper may implement this method which takes in a VitessceConfig instance and modifies it by adding datasets, visualization components, and view coordinations. Implementations of this method may create an opinionated view config based on inferred use cases.

Parameters

vc (VitessceConfig) – The view config instance.

convert_and_save(dataset_uid, obj_i)[source]

Fill in the file_def_creators array. Each function added to this list should take in a base URL and generate a Vitessce file definition. If this wrapper is wrapping local data, then create routes and fill in the routes array. This method is void, should not return anything.

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

  • obj_i (int) – Within the dataset, the index of this data wrapper object.

class vitessce.wrappers.MultiImageWrapper(image_wrappers, use_physical_size_scaling=False, **kwargs)[source]

Wrap multiple imaging datasets by creating an instance of the MultiImageWrapper class.

Parameters

Abstract constructor to be inherited by dataset wrapper classes.

Parameters

out_dir (str) – The path to a local directory used for data processing outputs. By default, uses a temp. directory.

convert_and_save(dataset_uid, obj_i)[source]

Fill in the file_def_creators array. Each function added to this list should take in a base URL and generate a Vitessce file definition. If this wrapper is wrapping local data, then create routes and fill in the routes array. This method is void, should not return anything.

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

  • obj_i (int) – Within the dataset, the index of this data wrapper object.

class vitessce.wrappers.OmeTiffWrapper(img_path=None, offsets_path=None, img_url=None, offsets_url=None, name='', transformation_matrix=None, is_bitmask=False, **kwargs)[source]

Wrap an OME-TIFF File by creating an instance of the OmeTiffWrapper class.

Parameters

Abstract constructor to be inherited by dataset wrapper classes.

Parameters

out_dir (str) – The path to a local directory used for data processing outputs. By default, uses a temp. directory.

convert_and_save(dataset_uid, obj_i)[source]

Fill in the file_def_creators array. Each function added to this list should take in a base URL and generate a Vitessce file definition. If this wrapper is wrapping local data, then create routes and fill in the routes array. This method is void, should not return anything.

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

  • obj_i (int) – Within the dataset, the index of this data wrapper object.

class vitessce.wrappers.SnapWrapper(in_mtx, in_barcodes_df, in_bins_df, in_clusters_df, starting_resolution=5000, **kwargs)[source]

Abstract constructor to be inherited by dataset wrapper classes.

Parameters

out_dir (str) – The path to a local directory used for data processing outputs. By default, uses a temp. directory.

auto_view_config(vc)[source]

Auto view configuration is intended to be used internally by the VitessceConfig.from_object method. Each subclass of AbstractWrapper may implement this method which takes in a VitessceConfig instance and modifies it by adding datasets, visualization components, and view coordinations. Implementations of this method may create an opinionated view config based on inferred use cases.

Parameters

vc (VitessceConfig) – The view config instance.

convert_and_save(dataset_uid, obj_i)[source]

Fill in the file_def_creators array. Each function added to this list should take in a base URL and generate a Vitessce file definition. If this wrapper is wrapping local data, then create routes and fill in the routes array. This method is void, should not return anything.

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

  • obj_i (int) – Within the dataset, the index of this data wrapper object.

vitessce.export

vitessce.export.export_to_files(config, base_url, out_dir='.')[source]
Parameters
  • config (VitessceConfig) – The Vitessce view config to export to files.

  • out_dir (str) – The path to the output directory. By default, the current directory.

  • base_url (str) – The URL on which the files will be served.

Returns

The config as a dict, with urls filled in.

Return type

dict

vitessce.export.export_to_s3(config, s3, bucket_name, prefix='')[source]
Parameters
  • config (VitessceConfig) – The Vitessce view config to export to S3.

  • s3 (boto3.resource) – A boto3 S3 resource object with permission to upload to the specified bucket.

  • bucket_name (str) – The name of the bucket to which to upload.

  • prefix (str) – The prefix path for the bucket keys (think subdirectory).

Returns

The config as a dict, with S3 urls filled in.

Return type

dict