fix(janelia example): Adding Janelia COSEM example notebook

Author: ayenpure

examples/jupyter/janelia_cosem_dataset.ipynb

@@ -0,0 +1,165 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "4cb17f8e-d21c-44fe-91f1-91edb1440023",
+   "metadata": {},
+   "source": [
+    "### 1. Load a Janelia COSEM Dataset into Xarray\n",
+    "\n",
+    "This function, `open_cosem_dataset`, helps load a 3D image volume from the [Janelia COSEM](https://www.janelia.org/project-team/cosem) dataset into an `xarray.Dataset`. It does the following:\n",
+    "\n",
+    "- Constructs the full URL from the dataset root and group path.\n",
+    "- Opens a Zarr array using anonymous access via `fsspec`.\n",
+    "- Extracts voxel spacing metadata (in nanometers) and uses it to create physical coordinates (in meters).\n",
+    "- Wraps the data as an `xarray.DataArray` and then into a `Dataset` for ease of use.\n",
+    "\n",
+    "The result is a spatially aware dataset, with proper coordinates, ready for visualization or analysis.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "362a7c99-9b51-40d5-82c0-c9e786e2dbc0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr\n",
+    "import fsspec\n",
+    "import zarr\n",
+    "import numpy as np\n",
+    "\n",
+    "\n",
+    "def open_cosem_dataset(dataset_url, group_path, var_name=\"values\"):\n",
+    "    \"\"\"\n",
+    "    Open a COSEM Zarr volume as an xarray.Dataset with physical coordinates.\n",
+    "\n",
+    "    Parameters\n",
+    "    ----------\n",
+    "    dataset_url : str\n",
+    "        e.g. \"s3://janelia-cosem-datasets/jrc_hela-1/jrc_hela-1.zarr\"\n",
+    "    group_path : str\n",
+    "        e.g. \"recon-1/em/fibsem-uint8/s4\"\n",
+    "    var_name : str\n",
+    "        Name to assign to the variable in the Dataset\n",
+    "\n",
+    "    Returns\n",
+    "    -------\n",
+    "    xr.Dataset\n",
+    "    \"\"\"\n",
+    "    # Open remote store\n",
+    "    full_url = f\"{dataset_url}/{group_path}\"\n",
+    "    z = zarr.open_array(full_url, mode=\"r\", storage_options={\"anon\": True})\n",
+    "\n",
+    "    # Default dims (Z, Y, X in COSEM, we'll reverse to X, Y, Z for xarray consistency)\n",
+    "    shape = z.shape\n",
+    "    dims = [\"z\", \"y\", \"x\"]\n",
+    "    if len(shape) != 3:\n",
+    "        raise ValueError(f\"Expected 3D data, got shape: {shape}\")\n",
+    "\n",
+    "    # Try to get voxel spacing in nm\n",
+    "    voxel_size_nm = z.attrs.get(\"pixelResolution\", {}).get(\n",
+    "        \"dimensions\", [4.0, 4.0, 4.0]\n",
+    "    )  # [Z, Y, X]\n",
+    "\n",
+    "    # Build coordinate arrays in physical units (meters)\n",
+    "    coords = {}\n",
+    "    for dim, size, spacing_nm in zip(dims, shape, voxel_size_nm):\n",
+    "        coords[dim] = np.arange(size) * spacing_nm * 1e-9  # convert nm → meters\n",
+    "\n",
+    "    # Construct DataArray with coords\n",
+    "    da = xr.DataArray(z, dims=dims, coords=coords, attrs=dict(z.attrs))\n",
+    "\n",
+    "    # Wrap into a Dataset\n",
+    "    ds = xr.Dataset({var_name: da})\n",
+    "    return ds"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "251c71cd-7db9-4ab9-8d02-92dfe0f693c6",
+   "metadata": {},
+   "source": [
+    "### 2. Retrieve the COSEM Dataset\n",
+    "\n",
+    "Here, we use the `open_cosem_dataset` function to load a specific FIB-SEM volume from the COSEM dataset collection:\n",
+    "\n",
+    "- `url` points to the dataset root in the S3 bucket.\n",
+    "- `group` identifies the subvolume (at a particular resolution level).\n",
+    "\n",
+    "The result is assigned to `ds`, an `xarray.Dataset` that includes:\n",
+    "\n",
+    "- A single data variable called `\"values\"`,\n",
+    "- Dimensions named `z`, `y`, and `x`,\n",
+    "- Coordinates in physical space (meters), based on metadata."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2f23562c-bc1b-4e60-b372-d660be6c6bb7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "url = \"s3://janelia-cosem-datasets/jrc_hela-1/jrc_hela-1.zarr\"\n",
+    "group = \"recon-1/em/fibsem-uint8/s4\"\n",
+    "\n",
+    "ds = open_cosem_dataset(url, group)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "234cd32a-2675-439e-9202-58ea492557e7",
+   "metadata": {},
+   "source": [
+    "### 3. Visualize with Pan3D Viewer\n",
+    "\n",
+    "We now create a `Pan3D` viewer instance to visualize the dataset.\n",
+    "\n",
+    "- The dataset `ds` is passed to `XArrayViewer`, which sets up a Trame-based UI for interactive volume exploration.\n",
+    "- Once `viewer.ui.ready` resolves, the viewer is fully initialized.\n",
+    "- The `viewer.ui` object can be rendered directly in the notebook (if supported), or externally in a browser window.\n",
+    "\n",
+    "This viewer makes it easy to inspect and explore 3D microscopy datasets with physical scale preserved.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "264f7e80-578f-4b65-b247-dd5f87c2ba17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create the instance of the viewer, and pass the filter to the pipeline argument\n",
+    "\n",
+    "from pan3d.viewers.preview import XArrayViewer\n",
+    "\n",
+    "viewer = XArrayViewer(xarray=ds, server=\"preview\")\n",
+    "await viewer.ui.ready\n",
+    "\n",
+    "viewer.ui"
+   ]
+  }
+ ],
+ "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.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}