Marimo notebook conversion

.github/workflows/docs.yml

@@ -14,5 +14,6 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y pandoc
-      - run: uv sync --extra docs --extra all
+      - run: uv sync --extra docs  --extra notebook --extra all
+      - run: uv run marimo export html-wasm docs/notebooks/marimo-wasm.mo.py -o docs/_static/mo/marimo-wasm.mo.html --mode edit
       - run: uv run make html

.github/workflows/test_widget.yml

@@ -29,11 +29,11 @@ jobs:
       - name: Install vitessce
         run: uv sync --extra dev --extra all --extra notebook
       - name: Export Jupyter notebook to HTML
-        run: uv run jupyter nbconvert --to=html --execute docs/notebooks/widget_from_dict.ipynb
+        run: uv run jupyter nbconvert --to=html --execute docs/notebooks/__ipynb__/widget_from_dict.ipynb
       - name: Export Marimo notebook to HTML
-        run: uv run marimo export html docs/notebooks/marimo.py -o docs/notebooks/marimo.html
+        run: uv run marimo export html docs/notebooks/marimo.mo.py -o docs/notebooks/marimo.mo.html
       - name: Export Marimo notebook to HTML-WASM
-        run: uv run marimo export html-wasm docs/notebooks/marimo-wasm.py -o docs/notebooks/marimo-wasm.html --mode edit
+        run: uv run marimo export html-wasm docs/notebooks/marimo-wasm.mo.py -o docs/notebooks/marimo-wasm.mo.html --mode edit
       - name: Check that widget renders in HTML output using Playwright
         run: pnpm exec playwright test
         working-directory: ./tests-widget

.gitignore

@@ -11,14 +11,23 @@ tests/data/*
 !tests/data/test.ome.tif
 ./notebooks/
 docs/notebooks/data/
+docs/notebooks/data-cropped/
+docs/notebooks/kpmp-2024/
+docs/notebooks/segmentations/
+docs/notebooks/*.json
 docs/notebooks/*.html
+docs/notebooks/*.ipynb
+docs/notebooks/*.zarr/
 __pycache__/
 .snakemake/
 .coverage
 demos/*/data/
 demos/*/vitessce.local.json
 demos/*/vitessce.remote.json
 .pytest_cache/
+__marimo__/
+assets/
+docs/_static/mo/
 
 # Compiled javascript
 vitessce/static/

docs/conf.py

@@ -3,6 +3,7 @@
 import sys
 import glob
 from os.path import join
+import json
 
 import vitessce
 
@@ -123,9 +124,39 @@ def find_source():
 # -- Strip notebook output -------------------------------------------------
 
 
-for filename in glob.glob(join('notebooks', '*.ipynb'), recursive=True):
+for filename in glob.glob(join('notebooks', "__ipynb__", '*.ipynb'), recursive=True):
     ntbk = nbclean.NotebookCleaner(filename)
     ntbk.clear('stderr')
     ntbk.clear('output')
     ntbk.remove_cells(empty=True)
+    ntbk.remove_cells(search_text="import marimo as mo")
     ntbk.save(filename)
+
+    # Add missing metadata, to enable the code to be interpreted as Python code
+    # for syntax highlighting when rendered by nbsphinx.
+    with open(filename, 'r') as f:
+        ntbk_json = json.load(f)
+    with open(filename, 'w') as f:
+        if len(ntbk_json['metadata']) == 0:
+            # If the metadata is empty, we add the default metadata.
+            # This is needed for nbsphinx to render the notebook correctly.
+            ntbk_json['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.10.14"
+                }
+            }
+        json.dump(ntbk_json, f, indent=2)

docs/data_examples.rst

@@ -5,7 +5,7 @@ Data preparation examples
 .. toctree::
    :maxdepth: 2
 
-   notebooks/data_export_s3
-   notebooks/data_export_files
-   notebooks/widget_brain_with_base_dir
-   notebooks/widget_brain_h5ad
+   notebooks/__ipynb__/data_export_s3
+   notebooks/__ipynb__/data_export_files
+   notebooks/__ipynb__/widget_brain_with_base_dir
+   notebooks/__ipynb__/widget_brain_h5ad

docs/notebooks/__ipynb__/cellbrowser_to_vitessce_config_conversion.ipynb

@@ -0,0 +1,190 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "MJUe",
+      "metadata": {
+        "marimo": {
+          "config": {
+            "hide_code": true
+          }
+        }
+      },
+      "source": [
+        "# Load UCSC Cell Browser project in Vitessce"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "vblA",
+      "metadata": {
+        "marimo": {
+          "config": {
+            "hide_code": true
+          }
+        }
+      },
+      "source": [
+        "This notebook shows you how to use the `convert_cell_browser_project_to_anndata` function, which allows you to take an existing project, published in https://cells.ucsc.edu/ and:\n",
+        "1. Convert it into the AnnData format that is supported by Vitessce\n",
+        "2. Save the AnnData object as a Zarr store\n",
+        "3. Configure Vitessce with the AnnData-Zarr store\n",
+        "4. Render a Vitessce widget based on the config (step 3) directly in the notebook.\n",
+        "\n",
+        "The dataset that you choose to convert needs to be a valid UCSC Cell Browser \"project\", accessible from https://cells.ucsc.edu/, with a configuration available in https://github.com/ucscGenomeBrowser/cellbrowser-confs\n",
+        "\n",
+        "The `convert_cell_browser_project_to_anndata` function takes the name of that project as an input. For example, to convert this project, https://cells.ucsc.edu/?ds=adultPancreas, you will neeed to pass `\"adultPancreas\"` as the project name."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "bkHC",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "import json\n",
+        "from os.path import join\n",
+        "from vitessce import (\n",
+        "    convert_cell_browser_project_to_anndata,\n",
+        "    AnnDataWrapper,\n",
+        "    VitessceConfig,\n",
+        ")\n",
+        "from vitessce.data_utils import VAR_CHUNK_SIZE"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "lEQa",
+      "metadata": {
+        "marimo": {
+          "config": {
+            "hide_code": true
+          }
+        }
+      },
+      "source": [
+        "## 1. Convert UCSC Cell Browser project to a format that is supported by Vitessce\n",
+        "#### Output:\n",
+        "An AnnData object"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "PKri",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# Example run, coverting \"adultPancreas\" project:\n",
+        "adata = convert_cell_browser_project_to_anndata(project_name=\"adultPancreas\", keep_only_marker_genes=True)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "Xref",
+      "metadata": {
+        "marimo": {
+          "config": {
+            "hide_code": true
+          }
+        }
+      },
+      "source": [
+        "## 2. Save the AnnData object as a Zarr store"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "SFPL",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "zarr_filepath = join(\"data\", \"out.adata.zarr\")\n",
+        "os.makedirs(os.path.dirname(zarr_filepath), exist_ok=True)\n",
+        "adata.write_zarr(zarr_filepath, chunks=[adata.shape[0], VAR_CHUNK_SIZE])"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "BYtC",
+      "metadata": {
+        "marimo": {
+          "config": {
+            "hide_code": true
+          }
+        }
+      },
+      "source": [
+        "## 3. Configure Vitessce with the AnnData-Zarr store"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "RGSE",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "anndata_wrapper_inst = AnnDataWrapper(\n",
+        "    adata_path=zarr_filepath,\n",
+        "    obs_feature_matrix_path=\"X\",\n",
+        "    obs_embedding_paths=[\"obsm/X_tsne\"],\n",
+        "    obs_embedding_names=[\"t-SNE\"],\n",
+        "    obs_set_paths=[\"obs/cluster\", \"obs/age\"],\n",
+        "    obs_set_names=[\"cluster\", \"age\"],\n",
+        ")\n",
+        "vc = VitessceConfig(schema_version=\"1.0.15\", name=\"Vitessce configuration for CellBrowser project adultPancreas\")\n",
+        "anndata_wrapper_inst.auto_view_config(vc)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "Kclp",
+      "metadata": {
+        "marimo": {
+          "config": {
+            "hide_code": true
+          }
+        }
+      },
+      "source": [
+        "## 4. Render the Vitessce widget"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "emfo",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "vw = vc.widget()\n",
+        "vw"
+      ]
+    }
+  ],
+  "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.10.14"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}