{
"cells": [
{
"cell_type": "markdown",
"id": "465fef63",
"metadata": {},
"source": [
"# Cross integration: Multiple ADT + ATAC\n",
"\n",
"Cross integration combines batches that all measure the same modalities. The task is to remove batch effects and keep the biological structure. This tutorial is for batches that each hold ADT and ATAC peaks, with no RNA. It runs StabMap and UINMF on `D58mini`, 3,000 cells in two batches of the benchmark dataset `D58`, and then on data in your own format.\n",
"\n",
"StabMap and UINMF run on Linux and macOS (Apple silicon), and UINMF has no Windows environment. On Windows, [open this notebook in Colab](https://colab.research.google.com/github/DSichang/scMultiBench/blob/main/notebooks/tutorial_cross_adt_atac.ipynb): sections 1 to 4 take about 6 minutes there."
]
},
{
"cell_type": "markdown",
"id": "13f33fb3",
"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": "e13cbade",
"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": "50e632cc",
"metadata": {},
"source": [
"## 2. Download the data and the environments\n",
"\n",
"`mtb.data.fetch` downloads `D58mini` (7 MB) once. `mtb.env.install` downloads the environments for StabMap and UINMF. On Linux the download is 0.9 GB. On macOS it is 0.7 GB."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "bad2be46",
"metadata": {},
"outputs": [],
"source": [
"import multibench as mtb\n",
"import pandas as pd\n",
"\n",
"pd.set_option(\"display.max_columns\", None) # show every column of the tables\n",
"\n",
"mtb.data.fetch(\"D58mini\")\n",
"METHODS = [\"StabMap\", \"UINMF\"]\n",
"envs = mtb.env.install(METHODS)"
]
},
{
"cell_type": "markdown",
"id": "0476800c",
"metadata": {},
"source": [
"## 3. Run the methods\n",
"\n",
"`run` runs each method on `D58mini` and [scores its output](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. The batch metrics measure how well the batches mix. The classification scores measure how well the cell types learned on one batch are predicted in the other batches. 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/D58mini\")` reloads these results later.\n",
"\n",
" "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9b31deb0",
"metadata": {},
"outputs": [],
"source": [
"res = mtb.run(\"D58mini\", \"cross\", methods=METHODS, out_dir=\"out/D58mini\")\n",
"res.summary"
]
},
{
"cell_type": "markdown",
"id": "6e40a06e",
"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, green for batch correction, pink for classification. 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": "c7d10565",
"metadata": {},
"outputs": [],
"source": [
"res.plot()"
]
},
{
"cell_type": "markdown",
"id": "110f4a31",
"metadata": {},
"source": [
"## 5. Your own data\n",
"\n",
"Your data needs raw ADT counts in one `.h5ad` file and an ATAC peak matrix of the same cells in another, with a cell type and a batch for each cell.\n",
"\n",
"The methods of this task read two batches.\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 [another number of donors](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-donors).\n",
"\n",
"\n",
"Details: export
\n",
"\n",
"When the ADT file also holds a matrix in `obsm` under a name that does not start with `X_`, `export_dataset` asks which one is the protein matrix. `X_umap` and `X_pca` are left alone.\n",
"\n",
"The batches are numbered in the sorted order of their names, read as text: donors `A`, `B` and `C` become batches 1, 2 and 3, and `10` comes before `2`.\n",
"\n",
"For one AnnData per batch, call `export_dataset` once per batch with `batch_index=N` instead of `batch=`.\n",
"\n",
" "
]
},
{
"cell_type": "markdown",
"id": "ae1eda0a",
"metadata": {},
"source": [
"The next cell writes two small example files, `my_adt.h5ad` and `my_atac.h5ad`, from 60% of the cells of `D58mini`, with a batch column. Skip it for your own data."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "528c2d69",
"metadata": {},
"outputs": [],
"source": [
"mtb.data.write_example(\"D58mini\")"
]
},
{
"cell_type": "markdown",
"id": "0f914952",
"metadata": {},
"source": [
"Read your files. For your own data, change every file name marked `# <-`. On Colab, upload the files first: click the folder icon on the left, then the upload icon."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f4593cfe",
"metadata": {},
"outputs": [],
"source": [
"import anndata as ad\n",
"\n",
"adt = ad.read_h5ad(\"my_adt.h5ad\") # <- your protein (ADT) file, every batch\n",
"atac = ad.read_h5ad(\"my_atac.h5ad\") # <- your peak file, the same cells\n",
"print(adt)\n",
"print(atac)"
]
},
{
"cell_type": "markdown",
"id": "200acb9b",
"metadata": {},
"source": [
"Write the dataset folder. Change each name in quotes marked `# <-` to one the printout above lists for your files, with its prefix, as `\"obs:celltype\"`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4f581c30",
"metadata": {},
"outputs": [],
"source": [
"NAME = \"MYCROSS_ADT_ATAC\" # <- a new name for your own data\n",
"mtb.io.export_dataset(adt, \"mydata/\" + NAME,\n",
" rna=None, # this data has no RNA\n",
" adt=\"X\", # <- where the proteins (ADT) are\n",
" atac=atac, # the ATAC file, peak counts in X\n",
" atac_kind=\"peak\", # the methods here read peaks\n",
" labels=\"obs:celltype\", # <- the cell-type column\n",
" batch=\"obs:batch\", # <- the batch or donor column\n",
" category=\"cross\", overwrite=True)\n",
"mtb.scan(\"mydata/\" + NAME, \"cross\", methods=METHODS)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9730b14b",
"metadata": {},
"outputs": [],
"source": [
"mine = mtb.run(\"mydata/\" + NAME, \"cross\", methods=METHODS,\n",
" out_dir=\"out/\" + NAME)\n",
"mine.summary"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b1d257ba",
"metadata": {},
"outputs": [],
"source": [
"mine.plot()"
]
},
{
"cell_type": "markdown",
"id": "701041a3",
"metadata": {},
"source": [
"## 6. Every method of this task\n",
"\n",
"5 methods run this task. [This notebook](https://colab.research.google.com/github/DSichang/scMultiBench/blob/main/notebooks/tutorial_cross_adt_atac_all.ipynb) runs them all. Its 4 environments download 12.1 GB on a computer without a GPU and 15.5 GB on one with a GPU."
]
},
{
"cell_type": "markdown",
"id": "16c42316",
"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",
"| batch metrics use the wrong batches | `res.rescore(batch=...)`, with one batch per cell, scores again without running the methods |\n",
"\n",
" "
]
},
{
"cell_type": "markdown",
"id": "3f933eb3",
"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
}