{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "be2810c7-7f5c-4a0c-b3cf-5a75e9a45406",
   "metadata": {},
   "outputs": [],
   "source": [
    "# This cell is to allow automatic notebook generation for docs\n",
    "# You may want to comment this out if you have paste3 installed\n",
    "import sys\n",
    "from pathlib import Path\n",
    "\n",
    "sys.path.insert(0, str(Path.cwd().parent.parent.parent / \"src\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ed2400f-074c-41c1-9b9c-c4164e3e35ff",
   "metadata": {},
   "source": [
    "# Using the PASTE/PASTE2 algorithm through a unifying API\n",
    "\n",
    "This noteook highlights the creation of slices (the `Slice` class) and datasets (the `AlignmentDataset` class), and the usage of the `pairwise_align` and `center_align` methods of the `AlignmentDataset` class.\n",
    "\n",
    "**This notebook primarily highlights how you would use the `paste3` package in either the `PASTE` (i.e. full alignment) mode, or the `PASTE2` (i.e. partial alignment) mode.**. This API also closely reflects how our napari plugin works under the hood, so getting familiar with this API will also help you get familiar with the various options available to you in the plugin."
   ]
  },
  {
   "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 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 `scanpy` library. (Note: This is roughly equivalent to doing `scanpy.pl.spatial(<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
}