{
"cells": [
{
"cell_type": "markdown",
"id": "509c9d78",
"metadata": {},
"source": [
"# Diagonal integration: [RNA, ATAC]\n",
"\n",
"Diagonal integration combines RNA and ATAC measured in different cells, with no pairing between them. If your RNA and ATAC come from the same cells, as in 10x Multiome, use [the vertical tutorial](https://colab.research.google.com/github/DSichang/scMultiBench/blob/main/notebooks/tutorial_vertical_rna_atac.ipynb). This tutorial runs iNMF and online_iNMF on `D27mini`, the RNA and ATAC of 3,000 cells of the benchmark dataset `D27` with the pairing left out, then on data in your own format.\n",
"\n",
"Most diagonal methods read ATAC as gene-activity scores, made beforehand with a tool such as Signac or ArchR. GLUE and Seurat_v5 read the peak matrix, and MultiMAP and Seurat_v3 need both. [The folder layout](https://dsichang.github.io/scMultiBench/tutorials/run/#folder-layout) lists each method's ATAC files.\n",
"\n",
"iNMF and online_iNMF run on Linux, Windows and macOS (Apple silicon). Or [open in Colab](https://colab.research.google.com/github/DSichang/scMultiBench/blob/main/notebooks/tutorial_diagonal_rna_atac.ipynb): sections 1 to 4 take about 6 minutes there."
]
},
{
"cell_type": "markdown",
"id": "c8640c24",
"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": "f23bff2a",
"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": "4a9d5c18",
"metadata": {},
"source": [
"## 2. Download the data and the environments\n",
"\n",
"`mtb.data.fetch` downloads `D27mini` (15 MB) once. `mtb.env.install` downloads the environments for iNMF and online_iNMF. On Linux the download is 0.9 GB. On Windows it is 0.3 GB. On macOS it is 0.7 GB."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0e4ccf49",
"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(\"D27mini\")\n",
"METHODS = [\"iNMF\", \"online_iNMF\"]\n",
"envs = mtb.env.install(METHODS)"
]
},
{
"cell_type": "markdown",
"id": "ef3489d7",
"metadata": {},
"source": [
"## 3. Run the methods\n",
"\n",
"`run` runs each method on `D27mini` 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 RNA and ATAC cells mix. The classification scores measure how well the cell types learned on one of them are predicted in the other. 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/D27mini\")` reloads these results later.\n",
"\n",
" "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "395ddf47",
"metadata": {},
"outputs": [],
"source": [
"res = mtb.run(\"D27mini\", \"diagonal\", methods=METHODS, out_dir=\"out/D27mini\")\n",
"res.summary"
]
},
{
"cell_type": "markdown",
"id": "3dbbafb7",
"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": "0be0780b",
"metadata": {},
"outputs": [],
"source": [
"res.plot()"
]
},
{
"cell_type": "markdown",
"id": "15c46006",
"metadata": {},
"source": [
"## 5. Your own data\n",
"\n",
"Your data needs raw RNA counts in one `.h5ad` file and ATAC in another, with a cell type for each cell in both. online_iNMF needs about 5,000 cells in total.\n",
"\n",
"Recipes cover [labels in a CSV file](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-labels-csv) and [no labels](https://dsichang.github.io/scMultiBench/tutorials/run/#recipe-no-labels).\n",
"\n",
"\n",
"Details: export
\n",
"\n",
"`labels=` needs the column in both files. With cell types for the RNA cells only, leave `labels=` out and follow the recipe for no labels.\n",
"\n",
" "
]
},
{
"cell_type": "markdown",
"id": "74dc6e04",
"metadata": {},
"source": [
"The next cell writes two small example files, `my_rna.h5ad` and `my_atac.h5ad`, from 90% of the RNA profiles and 90% of the ATAC profiles of `D27mini`. Skip it for your own data."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "736e5c9a",
"metadata": {},
"outputs": [],
"source": [
"mtb.data.write_example(\"D27mini\")"
]
},
{
"cell_type": "markdown",
"id": "d6a82b24",
"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": "8c8bb3ba",
"metadata": {},
"outputs": [],
"source": [
"import anndata as ad\n",
"\n",
"rna = ad.read_h5ad(\"my_rna.h5ad\") # <- your RNA file\n",
"atac = ad.read_h5ad(\"my_atac.h5ad\") # <- your ATAC file, other cells\n",
"print(rna)\n",
"print(atac)"
]
},
{
"cell_type": "markdown",
"id": "89a2d771",
"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": "d8fd6d79",
"metadata": {},
"outputs": [],
"source": [
"NAME = \"MYDIAG_RNA_ATAC\" # <- a new name for your own data\n",
"mtb.io.export_dataset(rna, \"mydata/\" + NAME,\n",
" rna=\"X\", # <- where the RNA counts are:\n",
" # \"X\" or \"layer:counts\"\n",
" atac=atac, # the ATAC file, values in X\n",
" atac_kind=\"gene_activity\", # <- or \"peak\"\n",
" labels=\"obs:celltype\", # <- the column in both files\n",
" category=\"diagonal\", overwrite=True)\n",
"mtb.scan(\"mydata/\" + NAME, \"diagonal\", methods=METHODS)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a5bf284f",
"metadata": {},
"outputs": [],
"source": [
"mine = mtb.run(\"mydata/\" + NAME, \"diagonal\", methods=METHODS,\n",
" out_dir=\"out/\" + NAME)\n",
"mine.summary"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "62ad6660",
"metadata": {},
"outputs": [],
"source": [
"mine.plot()"
]
},
{
"cell_type": "markdown",
"id": "41577fa3",
"metadata": {},
"source": [
"## 6. Stored results\n",
"\n",
"The package ships stored results for 11 methods on `D28`. `load_results` reads them and `mtb.plot.bubble` draws them, without running anything.\n",
"\n",
"\n",
"Details
\n",
"\n",
"There are no stored results for `D27mini`. `D28` is another benchmark dataset of the same task.\n",
"\n",
" "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d24de634",
"metadata": {},
"outputs": [],
"source": [
"stored = mtb.load_results(\"diagonal\", dataset=\"D28\")\n",
"mtb.plot.bubble(stored)"
]
},
{
"cell_type": "markdown",
"id": "b5c76c53",
"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_diagonal_rna_atac_all.ipynb) runs them all. Its 8 environments download 13.9 GB on a computer without a GPU and 13.2 GB on one with a GPU."
]
},
{
"cell_type": "markdown",
"id": "6bbd0fbb",
"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": "11cabf9a",
"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
}