napari plugin improvements (#94)

* selectable clustering variable for a dataset; sample data; added pooch as a dependency * moved dataset stuff to paste3.dataset; some tests * support for multiple overlap_fraction values for pairwise_align; tests for napari plugin * added notebook on using dataset api * napari is also a docs extra dependency * not forcing napari for docs; protected imports * adding layers after return to the main thread for center alignment
raphael-group · Nov 22, 2024 · 8760824 · 8760824
1 parent f5da616
commit 8760824
Show file tree

Hide file tree

Showing 13 changed files with 838 additions and 205 deletions.
diff --git a/docs/source/notebooks/paste3_dataset.ipynb b/docs/source/notebooks/paste3_dataset.ipynb
@@ -0,0 +1,237 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6ed2400f-074c-41c1-9b9c-c4164e3e35ff",
+   "metadata": {},
+   "source": [
+    "# `Slice` and `AlignmentDataset` objects"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "74234097-899a-450b-90c6-ecfc22fbc352",
+   "metadata": {},
+   "source": [
+    "The `paste3.dataset` module provides an easy-to-use API to access input datasets to the `paste3` alignment algorithms.\n",
+    "\n",
+    "The `Slice` class is a thin layer on top of an `AnnData` class, and an `AlignmentDataset` class is a collection of `Slice` objects."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "initial_id",
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-11-14T17:23:44.775643550Z",
+     "start_time": "2024-11-14T17:23:44.734901656Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "from paste3.dataset import AlignmentDataset\n",
+    "from paste3.napari.data.ondemand import get_file"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d75a8a52-f594-4ff9-b81d-f7e794f1f711",
+   "metadata": {},
+   "source": [
+    "Individual `Slice` objects are created by providing a path to an `.h5ad` file. Each `.h5ad` file is expected to contain an `AnnData` object, and is internally read using a `scanpy.read_h5ad`.\n",
+    "\n",
+    "Here we download and cache a few `.h5ad` files locally using a `paste3.napari.data.ondemand.get_file` call. These are the files available as the Sample Data in the `paste3` napari plugin."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bdcae26500ecd773",
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2024-11-14T17:23:44.898402985Z",
+     "start_time": "2024-11-14T17:23:44.775557096Z"
+    },
+    "collapsed": false,
+    "editable": true,
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "slice_files = [Path(f) for f in get_file(\"paste3_sample_patient_2_\")]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "30b304c3-236d-4cbb-8762-973665596109",
+   "metadata": {},
+   "source": [
+    "A dataset is created using the paths to the individual slices."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ab9f0325-ff80-4322-bd8d-a0e80920abce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dataset = AlignmentDataset(file_paths=slice_files)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a1cfd794-7890-4f5d-a6dd-bef3b0380980",
+   "metadata": {},
+   "source": [
+    "Any individual slice can be rendered in a jupyter notebook by simply typing the slice variable name in a cell, which renders the slice using the `squidpy` library. (Note: This is roughly equivalent to doing `squidpy.pl.spatial_scatter(<slice>.adata, ..)`)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "96c22c2e-d50b-40bc-b9c8-7092274dfdb7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dataset.slices[0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c2b5106-24c0-467e-8c38-71c39e711bd1",
+   "metadata": {},
+   "source": [
+    "An entire dataset can be rendered by typing the dataset variable name in a cell, which renders each slice in order."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "89a94821-197c-4fe4-b042-fcecca8355dd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dataset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "44319b2a-1eca-4eb4-91f4-fca1a5f9807c",
+   "metadata": {},
+   "source": [
+    "## Center Aligning a Dataset\n",
+    "\n",
+    "A dataset object can be center aligned in 2 steps:\n",
+    "\n",
+    "1. Find the \"center slice\" (or the \"consensus slice\") and similarity matrix between spots using the `<dataset>.find_center_slice` method. **This is a time consuming step and benefits from being run on a GPU-enabled environment.**\n",
+    "2. Use these values to center align the dataset using the `<dataset>.center_align` method.\n",
+    "\n",
+    "The first returned value is the aligned dataset, along with other useful information (rotations/translations). Here we ignore all returned values except the first one.\n",
+    "\n",
+    "Center alignment is explained in detail in the [Paste](https://www.nature.com/articles/s41592-022-01459-6) paper."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3d5fba70-a7e8-4924-8268-d3bdd8741e23",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "center_slice, pis = dataset.find_center_slice()\n",
+    "aligned_dataset, *_ = dataset.center_align(center_slice=center_slice, pis=pis)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "866dfa67-3150-4792-a3ae-b1b7a5a01635",
+   "metadata": {},
+   "source": [
+    "We can render the center slice and the aligned dataset as usual."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b05c39a9-5aa5-4a2d-be75-8c52029ec0e5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "center_slice"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3937cdf5-fd86-487b-ac3b-a9c97da27815",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "aligned_dataset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6616430c-76b2-48b9-9eb3-e69d87838cb7",
+   "metadata": {},
+   "source": [
+    "## Pairwise aligning a Dataset\n",
+    "\n",
+    "A dataset can be pairwise aligned using the `<dataset>.pairwise_align` method. An `overlap_fraction` value (between 0 and 1) can be specified.\n",
+    "\n",
+    "A value of `None` results in pairwise alignment that is identical to the approach mentioned in the [Paste](https://www.nature.com/articles/s41592-022-01459-6) paper. Any other value between 0 and 1 results in pairwise alignment explained in the [Paste2](https://pubmed.ncbi.nlm.nih.gov/37553263/) paper."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d5fa6853-f112-4cd6-8115-ed697b53d1cc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pairwise_aligned_dataset = dataset.pairwise_align(overlap_fraction=0.7)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "319621a8-aafb-48c4-b4bc-03f742578e77",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pairwise_aligned_dataset[0]"
+   ]
+  }
+ ],
+ "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.12.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}