Merge

Author: keller-mark

.coveragerc_omit

@@ -14,4 +14,5 @@ omit =
     src/vitessce/data_utils/multivec.py
     src/vitessce/data_utils/spatialdata_points_zorder.py
     src/vitessce/widget_plugins/demo_plugin.py
-    src/vitessce/widget_plugins/spatial_query.py
+    src/vitessce/widget_plugins/spatial_query.py
+    tests/*.py

.github/workflows/deploy.yml

@@ -38,7 +38,7 @@ jobs:
           path: ./docs-dist/html
       - name: Deploy package to PyPI
         continue-on-error: true
-        uses: pypa/gh-action-pypi-publish@v1.4.1
+        uses: pypa/gh-action-pypi-publish@release/v1.14
         with:
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -31,6 +31,18 @@ For a development installation (requires NodeJS and NPM),
     $ uv sync --extra dev --extra docs --extra all
 
 
+Alternatively, use conda:
+
+    $ conda create -n vitessce-dev python=3.12
+    $ conda activate vitessce-dev
+    $ pip install -e ".[dev,docs,all]"
+    
+Troubleshooting SpatialQuery installation on macOS:
+    
+    $ # Use the macOS clang instead of from homebrew.
+    $ CC=/usr/bin/clang CXX=/usr/bin/clang++ pip install -e ".[dev,docs,all,sq]"
+    
+
 ## Linting and testing
 
 ```sh

docs/notebooks/spatial_data_blobs.ipynb

@@ -30,7 +30,9 @@
    "outputs": [],
    "source": [
     "import spatialdata\n",
-    "from os.path import join"
+    "from os.path import join\n",
+    "import pandas as pd\n",
+    "from anndata import AnnData"
    ]
   },
   {
@@ -39,7 +41,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sdata = spatialdata.datasets.blobs()"
+    "sdata = spatialdata.datasets.blobs()\n",
+    "sdata"
    ]
   },
   {
@@ -48,7 +51,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "spatialdata_filepath = join(\"data\", \"blobs.spatialdata.zarr\")"
+    "# This blobs dataset only contains a table with a var.index corresponding to the shapes features.\n",
+    "# We need to construct a table with a var.index corresponding to the points features:\n",
+    "ddf = sdata.points[\"blobs_points\"]\n",
+    "unique_gene_ids = ddf[\"genes\"].unique().compute().tolist()\n",
+    "points_var_df = pd.DataFrame(index=unique_gene_ids, data=[], columns=[])\n",
+    "points_table = AnnData(var=points_var_df, obs=None, X=None)\n",
+    "sdata.tables['table_points'] = points_table"
    ]
   },
   {
@@ -57,7 +66,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sdata.write(spatialdata_filepath, overwrite=True)"
+    "spatialdata_filepath = join(\"data\", \"blobs.spatialdata.zarr\")"
    ]
   },
   {
@@ -66,13 +75,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Change data type of x and y columns from int64 to int32\n",
-    "# Temporary workaround, will be resolved by https://github.com/vitessce/vitessce/issues/2292\n",
-    "ddf = sdata[\"blobs_points\"]\n",
-    "ddf[\"x\"] = ddf[\"x\"].astype('int32')\n",
-    "ddf[\"y\"] = ddf[\"y\"].astype('int32')\n",
-    "sdata[\"blobs_points_2\"] = ddf\n",
-    "sdata.write_element(\"blobs_points_2\")"
+    "sdata.write(spatialdata_filepath, overwrite=True)"
    ]
   },
   {
@@ -112,23 +115,28 @@
     ")\n",
     "# Add data to the configuration:\n",
     "wrapper = SpatialDataWrapper(\n",
-    "    sdata_store=spatialdata_filepath,\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/blobs_image\",\n",
     "    obs_segmentations_path=\"labels/blobs_labels\",\n",
+    "    obs_embedding_paths=[\"tables/table/obsm/X_umap\"],\n",
+    "    obs_feature_matrix_path=\"tables/table/X\",\n",
     "    coordinate_system=\"global\",\n",
     "    coordination_values={\n",
     "        \"obsType\": \"blob\",\n",
+    "        \"featureType\": \"channel\",\n",
     "        \"fileUid\": \"my_unique_id\"\n",
     "    }\n",
     ")\n",
     "points_wrapper = SpatialDataWrapper(\n",
-    "    sdata_store=spatialdata_filepath,\n",
+    "    sdata_path=spatialdata_filepath,\n",
     "    # The following paths are relative to the root of the SpatialData zarr store on-disk.\n",
-    "    obs_points_path=\"points/blobs_points_2\",\n",
+    "    obs_points_path=\"points/blobs_points\",\n",
+    "    obs_feature_matrix_path=\"tables/table_points/X\", # TODO\n",
     "    coordinate_system=\"global\",\n",
     "    coordination_values={\n",
     "        \"obsType\": \"point\",\n",
+    "        \"featureType\": \"gene\",\n",
     "        \"fileUid\": \"other_unique_id\"\n",
     "    }\n",
     ")\n",
@@ -169,6 +177,7 @@
     "        'segmentationChannel': CL([{\n",
     "            'spatialChannelVisible': True,\n",
     "            'obsType': 'blob',\n",
+    "            \"featureType\": \"channel\",\n",
     "        }]),\n",
     "    }]),\n",
     "}, scope_prefix=get_initial_coordination_scope_prefix(\"A\", \"obsSegmentations\"))\n",
@@ -177,7 +186,10 @@
     "    'pointLayer': CL([{\n",
     "        \"fileUid\": \"other_unique_id\",\n",
     "        \"obsType\": \"point\",\n",
+    "        \"featureType\": \"gene\",\n",
     "        \"obsHighlight\": None,\n",
+    "        \"obsColorEncoding\": \"randomByFeature\",\n",
+    "        \"spatialLayerOpacity\": 1.0,\n",
     "    }]),\n",
     "}, scope_prefix=get_initial_coordination_scope_prefix(\"A\", \"obsPoints\"))\n",
     "\n",
@@ -202,6 +214,13 @@
     "vw"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "code",
    "execution_count": null,

docs/notebooks/widget_plugin_spatial-query.ipynb

@@ -19,20 +19,6 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "tags": []
-   },
-   "outputs": [],
-   "source": [
-    "#!pip install \"vitessce[all]==3.3.0\" esbuild_py anndata\n",
-    "!pip install \"mlxtend~=0.23.0\"\n",
-    "#!pip install -i \"https://test.pypi.org/simple/\" SpatialQuery\n",
-    "!pip install \"SpatialQuery @ git+https://github.com/ShaokunAn/Spatial-Query@main\""
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -44,41 +30,81 @@
     "    ViewType as vt,\n",
     "    CoordinationType as ct,\n",
     "    CoordinationLevel as CL,\n",
+    "    hconcat,\n",
+    "    vconcat,\n",
     ")\n",
     "from vitessce.widget_plugins import SpatialQueryPlugin"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download example dataset\n",
+    "\n",
+    "Download the `secondary_analysis.h5ad` file for sample `HBM838.LDFP.578` from the HuBMAP Portal at https://portal.hubmapconsortium.org/browse/dataset/5bf1e7b295343c4537206beda25aa4ca"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "adata = read_h5ad(join(\"data\", \"HBM987_KWLK_254\", \"secondary_analysis.h5ad\"))\n",
+    "import os\n",
+    "from os.path import join, isfile, isdir\n",
+    "from urllib.request import urlretrieve\n",
+    "\n",
+    "adata_path = join(\"data\", \"HBM987_KWLK_254\", \"secondary_analysis.h5ad\")\n",
     "zarr_path = join(\"data\", \"HBM987_KWLK_254\", \"secondary_analysis.h5ad.zarr\")\n",
+    "\n",
+    "if not isdir(join(\"data\")):\n",
+    "    os.makedirs(join(\"data\"), exist_ok=True)\n",
+    "    if not isdir(join(\"data\", \"HBM987_KWLK_254\")):\n",
+    "        os.makedirs(join(\"data\", \"HBM987_KWLK_254\"), exist_ok=True)\n",
+    "        if not isfile(adata_path):\n",
+    "            urlretrieve('https://assets.hubmapconsortium.org/0a21f3fa27109790483f2a0729be53de/secondary_analysis.h5ad', adata_path)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "adata = read_h5ad(adata_path)\n",
     "adata.write_zarr(zarr_path)"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "adata"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "plugin = SpatialQueryPlugin(adata)"
+    "plugin = SpatialQueryPlugin(adata, label_key=\"predicted_label\", spatial_key=\"X_spatial\", feature_name=\"hugo_symbol\")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "vc = VitessceConfig(schema_version=\"1.0.16\", name=\"Spatial-Query\")\n",
     "dataset = vc.add_dataset(\"Query results\").add_object(AnnDataWrapper(\n",
     "    adata_path=zarr_path,\n",
     "    obs_feature_matrix_path=\"X\",\n",
-    "    obs_set_paths=[\"obs/predicted.ASCT.celltype\"],\n",
+    "    obs_set_paths=[\"obs/predicted_label\"],\n",
     "    obs_set_names=[\"Cell Type\"],\n",
     "    obs_spots_path=\"obsm/X_spatial\",\n",
     "    feature_labels_path=\"var/hugo_symbol\",\n",
@@ -92,6 +118,8 @@
     "sets_view = vc.add_view(\"obsSets\", dataset=dataset)\n",
     "features_view = vc.add_view(\"featureList\", dataset=dataset)\n",
     "sq_view = vc.add_view(\"spatialQuery\", dataset=dataset)\n",
+    "sq_heatmap = vc.add_view(\"spatialQueryHeatmap\", dataset=dataset)\n",
+    "\n",
     "\n",
     "obs_set_selection_scope, = vc.add_coordination(\"obsSetSelection\",)\n",
     "obs_set_selection_scope.set_value(None)\n",
@@ -114,18 +142,25 @@
     "    ])\n",
     "})\n",
     "\n",
-    "vc.layout((spatial_view | (lc_view / features_view)) / (sets_view | sq_view));"
+    "vc.layout((spatial_view | (lc_view / features_view)) / hconcat(sets_view, sq_heatmap, sq_view, split=[1, 1, 1]));"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
     "vw = vc.widget(height=900, plugins=[plugin], remount_on_uid_change=False)\n",
     "vw"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -144,7 +179,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.12.13"
   }
  },
  "nbformat": 4,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vitessce"
-version = "3.7.9"
+version = "3.8.3"
 authors = [
   { name="Mark Keller", email="mark_keller@hms.harvard.edu" },
 ]
@@ -99,6 +99,13 @@ demos = [
   "snakemake",
   "pyyaml",
 ]
+# SpatialQuery
+sq = [
+  # When installing with `uv`, may need --no-build-isolation-package SpatialQuery
+  "pybind11",
+  # As of writing, `main` reflects SpatialQuery commit 9dde563 (April 4, 2026).
+  "SpatialQuery==0.0.4"
+]
 
 [dependency-groups]
 dev = [
@@ -125,6 +132,9 @@ override-dependencies = []
 [tool.hatch.build]
 exclude = [".github", "docs", "demos", "binder"]
 
+[tool.hatch.metadata]
+allow-direct-references = true
+
 [project.urls]
 repository = "https://github.com/vitessce/vitessce-python"
 

src/vitessce/file_def_utils.py

@@ -147,7 +147,7 @@ def gen_sdata_obs_segmentations_schema(options, path: str, table_path: str = "ta
     return options
 
 
-def gen_sdata_obs_points_schema(options, path: str, table_path: str = "tables/table", coordinate_system: Optional[str] = None) -> dict:
+def gen_sdata_obs_points_schema(options, path: str, table_path: str = "tables/table", coordinate_system: Optional[str] = None, feature_index_column: Optional[str] = None, morton_code_column: Optional[str] = None) -> dict:
     if path is not None:
         options["obsPoints"] = {
             "path": path
@@ -156,6 +156,10 @@ def gen_sdata_obs_points_schema(options, path: str, table_path: str = "tables/ta
             options["obsPoints"]['tablePath'] = table_path
         if coordinate_system is not None:
             options["obsPoints"]['coordinateSystem'] = coordinate_system
+        if feature_index_column is not None:
+            options["obsPoints"]['featureIndexColumn'] = feature_index_column
+        if morton_code_column is not None:
+            options["obsPoints"]['mortonCodeColumn'] = morton_code_column
     return options