notebooks/3-Comparative-Single-Cell-Embeddings.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c51533ea-fcc7-40d6-810c-c6fb410a5529",
   "metadata": {},
   "source": [
    "# Comparing Multiple Single-Cell Datasets with `cev`\n",
    "\n",
    "In the this notebook we're going to show that `jscatter` can be used in application-specific [Comparative Embedding Visualization](https://github.com/OzetteTech/comparative-embedding-visualization) widget (or `cev` in short) to enhance the exploration and comparison of single-cell (and other data) data.\n",
    "\n",
    "➡️ [For more infos about `cev` see github.com/OzetteTech/comparative-embedding-visualization](https://github.com/OzetteTech/comparative-embedding-visualization)\n",
    "\n",
    "Using the same single-cell data from [Mair et al., 2022](https://www.nature.com/articles/s41586-022-04718-w) that we already looked at in [1-Getting-Started.ipynb](1-Getting-Started.ipynb#Scalability). However, this time we will **_compare healthy against cancer tissue_** embeddings.\n",
    "\n",
    "As before, the data was clustered with [Ozette](https://www.ozette.com/)'s [FAUST method](https://doi.org/10.1016/j.patter.2021.100372) and transformed with [Ozette's Annotation Transformation](https://github.com/flekschas-ozette/ismb-biovis-2022) prior to being embedded with [UMAP](https://umap-learn.readthedocs.io/en/latest/).\n",
    "\n",
    "> 🚨 Shout-out Alert\n",
    "\n",
    "One more shout-out to [Trevor](https://trevorma.nz/) who led the development of [`cev`](comparative-embedding-visualization)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3860717-826f-4cdc-baac-cea2447950cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "# If you run this notebook in Google Colab, you need to manually install the following packages.\n",
    "# !pip install --quiet jupyter-scatter cev"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b3acc005-45c6-4394-9b2f-fbda3707bee5",
   "metadata": {},
   "outputs": [],
   "source": [
    "!mkdir -p data\n",
    "!curl -L -C - -o data/mair-2022-tumor-006-ozette.pq https://storage.googleapis.com/flekschas/jupyter-scatter-tutorial/mair-2022-tumor-006-ozette.pq\n",
    "!curl -L -C - -o data/mair-2022-tissue-138-ozette.pq https://storage.googleapis.com/flekschas/jupyter-scatter-tutorial/mair-2022-tissue-138-ozette.pq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "48e46180-bbc8-45ea-a46a-c6d3004c8611",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "mair_2022_tissue_ozette = pd.read_parquet(\"./data/mair-2022-tissue-138-ozette.pq\")\n",
    "mair_2022_tumor_ozette = pd.read_parquet(\"./data/mair-2022-tumor-006-ozette.pq\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48fd057f-04e6-4b6f-9995-8889d64a4f37",
   "metadata": {},
   "source": [
    "First we will plot two scatters with vanilla `jscatter` to get an idea of the nature of the healthy and cancer tissue embeddings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0bba4d0-2b3c-403e-a057-245ce28fcc17",
   "metadata": {},
   "outputs": [],
   "source": [
    "from itertools import cycle\n",
    "from jscatter import Scatter, compose, glasbey_light\n",
    "\n",
    "phenotypes = list(set(list(mair_2022_tumor_ozette.faustLabels.unique()) + list(mair_2022_tissue_ozette.faustLabels.unique())))\n",
    "\n",
    "colormap = dict(zip(phenotypes, cycle(glasbey_light[1:])))\n",
    "colormap[\"0_0_0_0_0\"] = (0.2, 0.2, 0.2, 1.0)\n",
    "\n",
    "config = dict(x='umapX', y='umapY', color_by='faustLabels', color_map=colormap, background_color=\"#111111\", axes=False)\n",
    "\n",
    "mair_2022_tissue_scatter = Scatter(data=mair_2022_tissue_ozette, **config)\n",
    "mair_2022_tumor_scatter = Scatter(data=mair_2022_tumor_ozette, **config)\n",
    "\n",
    "compose([(mair_2022_tissue_scatter, \"Healthy Tissue\"), (mair_2022_tumor_scatter, \"Cancer Tissue\")], row_height=640)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce7249d2-8beb-46ed-a4e5-3671b5e14b16",
   "metadata": {},
   "source": [
    "At a first glance you likely notice that both embedding visualizations looks fairly similar. This isn't surprising because the composition of cell types does not change drastically. Also, [Ozette's Annotation Transformation](https://github.com/flekschas-ozette/ismb-biovis-2022) ensures that both embeddings are aligned.\n",
    "\n",
    "A big question is which clusters differ the most. To answer this question we can analyze the neighborhood graph of the points. However, such computations are outside of \"vanilla\" `jscatter`. But we can build a tool around this and use `jscatter` to drive the visualization and point selections.\n",
    "\n",
    "We have done exactly this and created a tool+widget called _Comparative Embedding Visualization_ – or `cev` in short."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2d3a113e-b92b-4829-a431-be7b9542a056",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "from cev.widgets import Embedding, EmbeddingComparisonWidget\n",
    "\n",
    "tissue_ozette_embedding = Embedding.from_ozette(df=pd.read_parquet(\"./data/mair-2022-tissue-138-ozette.pq\"))\n",
    "tumor_ozette_embedding = Embedding.from_ozette(df=pd.read_parquet(\"./data/mair-2022-tumor-006-ozette.pq\"))\n",
    "\n",
    "tissue_vs_tumor = EmbeddingComparisonWidget(\n",
    "    tissue_ozette_embedding,\n",
    "    tumor_ozette_embedding,\n",
    "    titles=[\"Healthy Tissue\", \"Cancer Tissue\"],\n",
    "    metric=\"abundance\",\n",
    "    selection=\"phenotype\",\n",
    "    auto_zoom=True,\n",
    "    row_height=320,\n",
    "    background_color=\"#111111\",\n",
    ")\n",
    "\n",
    "tissue_vs_tumor"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b9dc762-eb56-483f-a080-829251534554",
   "metadata": {},
   "source": [
    "`cev` offers a bespoke interface to compare a pair embeddings (left vs right)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4262406d-059c-4b75-bf4b-3f14d86ffa1f",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}