{ "cells": [ { "cell_type": "markdown", "id": "269ffa3d", "metadata": {}, "source": [ "# Vertical integration: RNA + ADT\n", "\n", "Vertical integration combines modalities measured in the same cells. This tutorial is for RNA and surface protein, as in CITE-seq. It runs Matilda and sciPENN on `D11`, a CITE-seq dataset of 2,864 cells, and then on data in your own format.\n", "\n", "Matilda and sciPENN run on Linux, Windows and macOS (Apple silicon). Or [open in Colab](https://colab.research.google.com/github/DSichang/scMultiBench/blob/main/notebooks/tutorial_vertical_rna_adt.ipynb): sections 1 to 4 take about 7 minutes there." ] }, { "cell_type": "markdown", "id": "d9320c6b", "metadata": {}, "source": [ "## 1. Install\n", "\n", "pip may then print a note about restarting the kernel: no restart is needed, because the pins keep the numpy and pandas already installed." ] }, { "cell_type": "code", "execution_count": null, "id": "9da11b1b", "metadata": {}, "outputs": [], "source": [ "import numpy, pandas\n", "pins = f\"numpy=={numpy.__version__} pandas=={pandas.__version__}\"\n", "%pip install -q \"multibench-sc>=0.7.4\" {pins}" ] }, { "cell_type": "markdown", "id": "14bc2851", "metadata": {}, "source": [ "## 2. Download the data and the environments\n", "\n", "`mtb.data.fetch` downloads `D11` (11 MB) once. `mtb.env.install` downloads the environments for Matilda and sciPENN. On Linux the download is 1.1 GB on a computer without a GPU and 5.1 GB on one with a GPU. On Windows it is 0.3 GB and 2.8 GB. On macOS it is 0.7 GB." ] }, { "cell_type": "code", "execution_count": null, "id": "44c9bfb4", "metadata": {}, "outputs": [], "source": [ "import multibench as mtb\n", "\n", "mtb.data.fetch(\"D11\")\n", "METHODS = [\"Matilda\", \"sciPENN\"]\n", "envs = mtb.env.install(METHODS)" ] }, { "cell_type": "markdown", "id": "cfd6041b", "metadata": {}, "source": [ "## 3. Run the methods\n", "\n", "`run` runs each method on `D11` and scores its output with the [scIB metrics](https://dsichang.github.io/scMultiBench/tutorials/evaluate/#what-each-metric-measures). The clustering metrics score how well the embedding's clusters and neighbourhoods match the cell types, and how separate the clusters are. Higher is better for every metric.\n", "\n", "
\n", "Details\n", "\n", "`params={\"Method\": {\"key\": value}}` sets a method's parameters, and `mtb.params_for` lists them.\n", "\n", "`mtb.load_run(\"out/D11\")` reloads these results later.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "90a67f92", "metadata": {}, "outputs": [], "source": [ "res = mtb.run(\"D11\", \"vertical\", methods=METHODS, out_dir=\"out/D11\")\n", "res.summary" ] }, { "cell_type": "markdown", "id": "f9ea0b13", "metadata": {}, "source": [ "## 4. Plot\n", "\n", "`res.plot()` draws the scores as a bubble table. Circle size ranks the rows within each column and colour shows the value scaled per column, so a small gap can look large. `res.summary` has the values.\n", "\n", "
\n", "Details\n", "\n", "Metrics are grouped by family: blue for clustering. Each family starts with an `Overall` bar: each row's mean rank over the family's metrics, scaled so that the lowest gets the shortest bar.\n", "\n", "A column with fewer than two different values is drawn grey. A figure of one method is grey everywhere.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "4dc43091", "metadata": {}, "outputs": [], "source": [ "res.plot()" ] }, { "cell_type": "markdown", "id": "a6df2f8c", "metadata": {}, "source": [ "## 5. Your own data\n", "\n", "Your data needs raw counts for both modalities and a cell type for each cell, in one `.h5ad` file.\n", "\n", "Recipes cover [a 10x `.h5` file](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-10x-h5), [labels in a CSV file](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-labels-csv), [no labels](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-no-labels) and [several donors or samples](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-donors).\n", "\n", "
\n", "Details: export\n", "\n", "The example keeps the protein names in `adata.uns[\"protein_names\"]`. A DataFrame in `adata.obsm[\"protein\"]` brings its own names in its columns.\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "c29bd7c8", "metadata": {}, "source": [ "The next cell writes a small example file, `my_file.h5ad`, from 60% of the cells of `D11`. Skip it for your own data." ] }, { "cell_type": "code", "execution_count": null, "id": "0a6485f7", "metadata": {}, "outputs": [], "source": [ "mtb.data.write_example(\"D11\")" ] }, { "cell_type": "markdown", "id": "90aaee19", "metadata": {}, "source": [ "Read your file. For your own data, change the file name marked `# <-`. On Colab, upload the file first: click the folder icon on the left, then the upload icon." ] }, { "cell_type": "code", "execution_count": null, "id": "df7daf90", "metadata": {}, "outputs": [], "source": [ "import anndata as ad\n", "\n", "adata = ad.read_h5ad(\"my_file.h5ad\") # <- your file\n", "adata" ] }, { "cell_type": "markdown", "id": "cd78bc5f", "metadata": {}, "source": [ "Write the dataset folder. Change each name in quotes marked `# <-` to one the printout above lists for your file, with its prefix, as `\"obs:celltype\"` or `\"obsm:protein\"`." ] }, { "cell_type": "code", "execution_count": null, "id": "bb3d4567", "metadata": {}, "outputs": [], "source": [ "NAME = \"MYCITE\" # <- a new name for your own data\n", "mtb.io.export_dataset(adata, \"mydata/\" + NAME,\n", " rna=\"X\", # <- where the RNA counts are:\n", " # \"X\" or \"layer:counts\"\n", " adt=\"obsm:protein\", # <- where the proteins (ADT) are\n", " labels=\"obs:celltype\", # <- the cell-type column\n", " overwrite=True)\n", "mtb.scan(\"mydata/\" + NAME, \"vertical\", methods=METHODS)" ] }, { "cell_type": "code", "execution_count": null, "id": "8a089772", "metadata": {}, "outputs": [], "source": [ "mine = mtb.run(\"mydata/\" + NAME, \"vertical\", methods=METHODS,\n", " out_dir=\"out/\" + NAME)\n", "mine.summary" ] }, { "cell_type": "code", "execution_count": null, "id": "44cd0cbc", "metadata": {}, "outputs": [], "source": [ "mine.plot()" ] }, { "cell_type": "markdown", "id": "c322a42c", "metadata": {}, "source": [ "## 6. Stored results\n", "\n", "The package ships stored results for 13 methods on `D11`. `load_results` reads them and `mtb.plot.bubble` draws them, without running anything.\n", "\n", "
\n", "Details\n", "\n", "Scores of your runs differ a little from the stored ones: some methods, such as sciPENN, give a slightly different embedding on each run.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "11b95a51", "metadata": {}, "outputs": [], "source": [ "stored = mtb.load_results(\"vertical\", dataset=\"D11\")\n", "mtb.plot.bubble(stored)" ] }, { "cell_type": "markdown", "id": "29fe62e7", "metadata": {}, "source": [ "## 7. Every method of this task\n", "\n", "14 methods run this task. [This notebook](https://colab.research.google.com/github/DSichang/scMultiBench/blob/main/notebooks/tutorial_vertical_rna_adt_all.ipynb) runs them all. Its 13 environments download 24.5 GB on a computer without a GPU and 31.9 GB on one with a GPU." ] }, { "cell_type": "markdown", "id": "0169e4da", "metadata": {}, "source": [ "## Troubleshooting\n", "\n", "`res.summary[res.summary.status != \"scored\"]` lists each method that failed or was skipped. Its `reason` column ends with the method's error output.\n", "\n", "
\n", "Details\n", "\n", "| symptom | fix |\n", "|---|---|\n", "| a method fails on a small dataset | `mtb.scan` names what the method needs from the data's size in its `caveat` column |\n", "\n", "
" ] }, { "cell_type": "markdown", "id": "5f8a18e5", "metadata": {}, "source": [ "## Next steps\n", "\n", "- [Run a method](https://dsichang.github.io/scMultiBench/tutorials/run/), [Score an embedding](https://dsichang.github.io/scMultiBench/tutorials/evaluate/), [Load and plot results](https://dsichang.github.io/scMultiBench/tutorials/plot/) and [Discover methods](https://dsichang.github.io/scMultiBench/tutorials/discover/).\n", "- [Look at an embedding](https://dsichang.github.io/scMultiBench/tutorials/evaluate/#look-at-an-embedding) draws a method's embedding as a UMAP.\n", "- The [interactive explorer](https://shiny.maths.usyd.edu.au/scMultiBench/) has the full benchmark's rankings, with no install needed." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "version": "3.10" } }, "nbformat": 4, "nbformat_minor": 5 }