docs/notebooks/cellbrowser_to_vitessce_config_conversion.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "710bc947",
   "metadata": {},
   "source": [
    "# Load UCSC Cell Browser project in Vitessce"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fad939f6-bd8b-46f8-8dd1-f0816d8ca5b3",
   "metadata": {},
   "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": 5,
   "id": "532fea6a-69d4-4cac-8afb-6d334dbe7ca1",
   "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": "a8077cfd-abc2-488d-9d91-83bc29a0bbe9",
   "metadata": {},
   "source": [
    "## 1. Convert UCSC Cell Browser project to a format that is supported by Vitessce\n",
    "#### Output:\n",
    "An AnnData object\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "743c2d61-d98c-4e8d-a821-d5fe0ec2d93b",
   "metadata": {},
   "outputs": [],
   "source": [
    "## 3. Convert UCSC Cell Browser project to a Vitessce view config"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "6fb3e7dc-baf8-49e9-9d24-264bcd668b49",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Converting CellBrowser config for project adultPancreas to Anndata-Zarr object\n",
      "Successfully fetched configuration: https://cells.ucsc.edu/adultPancreas/dataset.json.\n",
      "CellBrowser config is valid. Proceeding further with conversion.\n",
      "Downloading expression matrix ...\n",
      "Successfully downloaded expression matrix https://cells.ucsc.edu/adultPancreas/exprMatrix.tsv.gz.\n",
      "Loading expression matrix into Anndata object ...\n",
      "This dataset uses the format identifier|symbol for the ad.obs gene names (e.g. “ENSG0123123.3|HOX3”). We are keeping only the symbol.\n",
      "Adding cell metadata to Anndata object ...\n",
      "Successfully downloaded metadata meta.tsv.\n",
      "Successful extraction of the following coordinates and URLS: {'X_tsne': 'tMinusSNE.coords.tsv.gz'}\n",
      "Adding X_tsne to Anndata object ...\n",
      "X_tsne successfully added.\n",
      "Done adding coordinates to the Anndata object.\n",
      "Filtering out all non-marker genes from Anndata object ...\n",
      "Successfully filtered out all non-marker genes from Anndata object.\n",
      "About to write the Anndata object to the Zarr store. The following properties will be saved:\n",
      "  Obs columns: ['cluster', 'age', 'age_unit', 'Key', 'experiment_name', 'fragAnalyzerRange', 'nCells', 'ng_ul', 'plate_nr', 'sample_recieve_date', 'chip_type', 'c1_chip_id', 'enrichment_method', 'capture_position', 'gene_body_coverage', 'intron_exon_ratio', 'mapped_reads', 'total_reads', 'n_genes']\n",
      "  Obsm keys: ['X_tsne']\n",
      "  Var columns: ['gene', 'n_cells']\n",
      "obsm X_tsne is an instance of DataFrame, converting it to numpy array.\n"
     ]
    }
   ],
   "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": "cf3cfcbe-4048-4a60-8988-b8c0eace23e2",
   "metadata": {},
   "source": [
    "## 2. Save the AnnData object as a Zarr store"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "8835ab53-2ee3-490e-a68c-c2d8952277a9",
   "metadata": {
    "scrolled": true
   },
   "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": "d61667b4-dc32-4376-bff1-b4a5bf74140f",
   "metadata": {},
   "source": [
    "## 3. Configure Vitessce with the AnnData-Zarr store"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "259c1804-2e67-4a92-bc90-5ba5e3dba7b3",
   "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": "22e7d2fd-2c2e-4ce5-b551-7809cdc6568e",
   "metadata": {},
   "source": [
    "## 4. Render the Vitessce widget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "cb9cb8e3-8ef4-49d9-b0a0-ba2f0fc80637",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "e5878bf30e1f4428a14604731928972d",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "VitessceWidget(config={'version': '1.0.15', 'name': 'Vitessce configuration for CellBrowser project adultPancr…"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vw = vc.widget()\n",
    "vw"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "774b8156-5cc6-4d17-884b-595957366230",
   "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.9.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}