Troubleshoot installation and update notebook

Author: keller-mark

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/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": [
@@ -48,37 +34,74 @@
     "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",
+    "        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": [
-    "plugin = SpatialQueryPlugin(adata)"
+    "adata"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plugin = SpatialQueryPlugin(adata, label_key=\"predicted_label\", spatial_key=\"X_spatial\", feature_name=\"hugo_symbol\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "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",
@@ -119,13 +142,20 @@
   },
   {
    "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 +174,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.12.13"
   }
  },
  "nbformat": 4,

pyproject.toml

@@ -99,6 +99,13 @@ demos = [
   "snakemake",
   "pyyaml",
 ]
+# SpatialQuery
+sq = [
+  # To install: uv sync --extra sq --no-build-isolation-package SpatialQuery
+  # or: uv sync --extra all --extra notebook --extra sq --no-build-isolation-package SpatialQuery
+  "pybind11",
+  "SpatialQuery @ git+https://github.com/ShaokunAn/Spatial-Query@main"
+]
 
 [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"