(feat): SpatialData wrapper

.coveragerc_omit

@@ -2,6 +2,7 @@
 omit =
     vitessce/config.py
     vitessce/export.py
+    vitessce/file_def_utils.py
     vitessce/routes.py
     vitessce/widget.py
     vitessce/wrappers.py
@@ -10,4 +11,6 @@ omit =
     vitessce/data_utils/anndata.py
     vitessce/data_utils/ome.py
     vitessce/data_utils/entities.py
-    vitessce/data_utils/multivec.py
+    vitessce/data_utils/multivec.py
+    vitessce/widget_plugins/demo_plugin.py
+    vitessce/widget_plugins/spatial_query.py

.github/workflows/test.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        version: ['3.8', '3.12']
+        version: ['3.9', '3.12']
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2

demos/fill_template.py

@@ -12,7 +12,7 @@ def render_json(dir_name, version_str, url_type, port):
 
     BASE_URL = {
         'local': f'http://localhost:{port}/{dir_name}/data/processed',
-        'remote': f'https://s3.amazonaws.com/vitessce-data/{version_str}/main/{dir_name}'
+        'remote': f'https://data-1.vitessce.io/{version_str}/main/{dir_name}'
     }
     BASE_URL_GCP = {
         'local': f'http://localhost:{port}/{dir_name}/data/processed',

docs/data_examples.rst

@@ -7,4 +7,5 @@ Data preparation examples
 
    notebooks/data_export_s3
    notebooks/data_export_files
-   notebooks/widget_brain_with_base_dir
+   notebooks/widget_brain_with_base_dir
+   notebooks/widget_brain_h5ad

docs/data_options.rst

@@ -106,5 +106,44 @@ Jupyter process: remote service like Colab/Binder; Files: remote & accessed via
 
 Unfortunately, this will not work because the remote server cannot access the files that are on another machine behind SSH.
 
+========================================================================
+Jupyter process: anywhere; Files: anywhere that can be accessed via Zarr
+========================================================================
 
+If the data is readable via Zarr (i.e., `zarr.storage.*Store`) and the Jupyter process can access the store contents, then the Vitessce widget can access the data by specifying the Zarr store as the data source for Vitessce data wrapper class instances.
+This is currently supported for the ``AnnDataWrapper`` class using the ``adata_store`` parameter (as opposed to ``adata_path`` or ``adata_url``).
+
+.. code-block:: python
+
+    from vitessce import VitessceConfig, AnnDataWrapper
+
+    # ...
+    adata.write_zarr("my_store.adata.zarr")
+
+    vc = VitessceConfig(name="My Vitessce Configuration")
+    vc.add_dataset(name="My Dataset").add_object(AnnDataWrapper(
+        adata_store="my_store.adata.zarr",
+        # ...
+    ))
+    # ...
+    vc.widget()
+
+
+Or, with a Zarr store instance (instead of a local string path to a DirectoryStore):
+
+.. code-block:: python
+
+    import zarr
+    from vitessce import VitessceConfig, AnnDataWrapper
+
+    # ...
+    store = zarr.storage.FSStore("s3://my_bucket/path/to/my_store.adata.zarr")
+
+    vc = VitessceConfig(name="My Vitessce Configuration")
+    vc.add_dataset(name="My Dataset").add_object(AnnDataWrapper(
+        adata_store=store,
+        # ...
+    ))
+    # ...
+    vc.widget()
 

docs/index.rst

@@ -48,6 +48,7 @@ The Vitessce widget is compatible with the following interactive Python platform
    api_config
    api_data
    data_options
+   widget_plugins
    screenshots
 
 

docs/notebooks/spatial_data.ipynb

@@ -0,0 +1,203 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "source": [
+    "# Vitessce Widget Tutorial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Visualization of SpatialData Object"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Import dependencies\n",
+    "\n",
+    "We need to import the classes and functions that we will be using from the corresponding packages."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%load_ext autoreload\n",
+    "%autoreload 2\n",
+    "\n",
+    "from pathlib import Path\n",
+    "from urllib.request import urlretrieve\n",
+    "import dask\n",
+    "\n",
+    "dask.config.set({'dataframe.query-planning-warning': False})\n",
+    "\n",
+    "from spatialdata import read_zarr\n",
+    "import scanpy as sc\n",
+    "\n",
+    "from vitessce import (\n",
+    "    VitessceConfig,\n",
+    "    Component as cm,\n",
+    "    CoordinationType as ct,\n",
+    "    CoordinationLevel as CL,\n",
+    "    AbstractWrapper,\n",
+    "    SpatialDataWrapper,\n",
+    "    get_initial_coordination_scope_prefix\n",
+    ")\n",
+    "from vitessce.data_utils import (\n",
+    "    optimize_adata,\n",
+    "    VAR_CHUNK_SIZE,\n",
+    ")\n",
+    "import zipfile\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "zip_filepath = Path(\"data/visium.spatialdata.zarr.zip\")\n",
+    "spatialdata_filepath = zip_filepath.with_suffix('')\n",
+    "if not zip_filepath.exists():\n",
+    "    spatialdata_filepath.parent.mkdir(exist_ok=True)\n",
+    "    urlretrieve('https://s3.embl.de/spatialdata/spatialdata-sandbox/visium_associated_xenium_io.zip', zip_filepath)\n",
+    "if not spatialdata_filepath.exists():\n",
+    "    with zipfile.ZipFile(zip_filepath,\"r\") as zip_ref:\n",
+    "        zip_ref.extractall(spatialdata_filepath.parent)\n",
+    "        (spatialdata_filepath.parent / \"data.zarr\").rename(spatialdata_filepath)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Load the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "spatialdata = read_zarr(spatialdata_filepath)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "spatialdata"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Create the Vitessce widget configuration\n",
+    "\n",
+    "Vitessce needs to know which pieces of data we are interested in visualizing, the visualization types we would like to use, and how we want to coordinate (or link) the views."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "vc = VitessceConfig(\n",
+    "    schema_version=\"1.0.16\",\n",
+    "    name='Visium SpatialData Demo (visium_associated_xenium_io)',\n",
+    "    description='From https://spatialdata.scverse.org/en/latest/tutorials/notebooks/datasets/README.html'\n",
+    ")\n",
+    "# Add data to the configuration:\n",
+    "wrapper = SpatialDataWrapper(\n",
+    "    sdata_path=spatialdata_filepath,\n",
+    "    # The following paths are relative to the root of the SpatialData zarr store on-disk.\n",
+    "    image_path=\"images/CytAssist_FFPE_Human_Breast_Cancer_full_image\",\n",
+    "    table_path=\"table/table\",\n",
+    "    obs_feature_matrix_path=\"table/table/X\",\n",
+    "    obs_spots_path=\"shapes/CytAssist_FFPE_Human_Breast_Cancer\",\n",
+    "    region=\"CytAssist_FFPE_Human_Breast_Cancer\",\n",
+    "    coordinate_system=\"global\",\n",
+    "    coordination_values={\n",
+    "        # The following tells Vitessce to consider each observation as a \"spot\"\n",
+    "        \"obsType\": \"spot\",\n",
+    "    }\n",
+    ")\n",
+    "dataset = vc.add_dataset(name='Breast Cancer Visium').add_object(wrapper)\n",
+    "\n",
+    "# Add views (visualizations) to the configuration:\n",
+    "spatial = vc.add_view(\"spatialBeta\", dataset=dataset)\n",
+    "feature_list = vc.add_view(cm.FEATURE_LIST, dataset=dataset)\n",
+    "layer_controller = vc.add_view(\"layerControllerBeta\", dataset=dataset)\n",
+    "vc.link_views_by_dict([spatial, layer_controller], {\n",
+    "    'imageLayer': CL([{\n",
+    "        'photometricInterpretation': 'RGB',\n",
+    "    }]),\n",
+    "}, scope_prefix=get_initial_coordination_scope_prefix(\"A\", \"image\"))\n",
+    "obs_sets = vc.add_view(cm.OBS_SETS, dataset=dataset)\n",
+    "vc.link_views([spatial, layer_controller, feature_list, obs_sets], ['obsType'], [wrapper.obs_type_label])\n",
+    "\n",
+    "# Layout the views\n",
+    "vc.layout(spatial | (feature_list / layer_controller / obs_sets));"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 4. Render the widget"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "vw = vc.widget()\n",
+    "vw"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}