Mosaic integration: Mixed, without shared modality¶
Mosaic integration combines batches that share only some modalities, and every mosaic method reads ATAC as peaks. This tutorial is for an RNA + ADT batch, an RNA + ATAC batch and an ADT batch, so no modality is in every batch. It runs StabMap and scMoMaT on D49mini, 4,500 cells of the benchmark dataset D49, and then on data in your own format.
StabMap and scMoMaT run on Linux, Windows and macOS (Apple silicon). Or open in Colab: sections 1 to 4 take about 11 minutes there.
1. Install¶
pip may then print a note about restarting the kernel: no restart is needed, because the pins keep the numpy and pandas already installed.
import numpy, pandas
pins = f"numpy=={numpy.__version__} pandas=={pandas.__version__}"
%pip install -q "multibench-sc>=0.7.4" {pins}
Note: you may need to restart the kernel to use updated packages.
2. Download the data and the environments¶
mtb.data.fetch downloads D49mini (5 MB) once. mtb.env.install downloads the environments for StabMap and scMoMaT. On Linux the download is 1.8 GB on a computer without a GPU and 5.4 GB on one with a GPU. On Windows it is 0.6 GB and 2.5 GB. On macOS it is 1.0 GB.
import multibench as mtb
import pandas as pd
pd.set_option("display.max_columns", None) # show every column of the tables
mtb.data.fetch("D49mini")
METHODS = ["StabMap", "scMoMaT"]
envs = mtb.env.install(METHODS)
downloading D49mini (5 MB) ...
3. Run the methods¶
run runs each method on D49mini and scores its output. 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. scMoMaT writes a graph: run scores that graph, which has no ASW, iASW or ASW_batch and no classification scores. Higher is better for every metric.
Details
params={"Method": {"key": value}} sets a method's parameters, and mtb.params_for lists them.
mtb.load_run("out/D49mini") reloads these results later.
res = mtb.run("D49mini", "mosaic", methods=METHODS, out_dir="out/D49mini")
res.summary
[run] StabMap (mosaic/D49mini) ... [run] -> scored (12.3s) ARI 0.388 [run] scMoMaT (mosaic/D49mini) ... [run] -> scored (90.8s) ARI 0.381
| method | status | ARI | NMI | ASW | iASW | iF1 | cLISI | ASW_batch | ARI_batch | NMI_batch | GC | iLISI | OCA | ACA | Spec | Sens | F1 | run_sec | caveat | reason | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | StabMap | scored | 0.3883 | 0.5641 | 0.5652 | 0.5474 | 0.3561 | 0.9688 | 0.7121 | 0.6783 | 0.6164 | 0.7709 | 0.1559 | 0.4866 | 0.3431 | 0.9751 | 0.3431 | 0.2985 | 12.3 | ||
| 1 | scMoMaT | scored | 0.3813 | 0.6256 | NaN | NaN | 0.3409 | 0.8590 | NaN | 0.9743 | 0.9719 | 0.9819 | 0.9053 | NaN | NaN | NaN | NaN | NaN | 90.8 |
4. Plot¶
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.
Details
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.
A column with fewer than two different values is drawn grey. A figure of one method is grey everywhere.
res.plot()
5. Your own data¶
Your data needs raw counts, with one .h5ad file per batch and modality and a cell type for each cell. Number the batches as below: RNA + ADT, then RNA + ATAC, then ADT. Give ATAC as peaks.
Every RNA file needs the same gene names and every ADT file the same protein names, in the same order. scMoMaT matches the features of two batches by position, and the check does not compare their names across batches.
Recipes cover a 10x .h5 file, labels in a CSV file and no labels.
Details: export
The folder layout lists the batch patterns and the methods that accept each one.
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.
The next cell writes five small example files, one per batch and modality, from the first 1,000 cells of each batch of D49mini. Skip it for your own data.
mtb.data.write_example("D49mini")
wrote my_rna1.h5ad: 1,000 cells. RNA counts in X, cell types in obs["celltype"]. wrote my_adt1.h5ad: 1,000 cells. protein counts in X, cell types in obs["celltype"]. wrote my_rna2.h5ad: 1,000 cells. RNA counts in X, cell types in obs["celltype"]. wrote my_atac2.h5ad: 1,000 cells. ATAC peak counts in X, cell types in obs["celltype"]. wrote my_adt3.h5ad: 1,000 cells. protein counts in X, cell types in obs["celltype"].
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.
import anndata as ad
rna1 = ad.read_h5ad("my_rna1.h5ad") # <- batch 1: your RNA file
adt1 = ad.read_h5ad("my_adt1.h5ad") # <- batch 1: proteins (ADT), same cells
rna2 = ad.read_h5ad("my_rna2.h5ad") # <- batch 2: your RNA file
atac2 = ad.read_h5ad("my_atac2.h5ad") # <- batch 2: peaks of the same cells
adt3 = ad.read_h5ad("my_adt3.h5ad") # <- batch 3: your protein (ADT) file
print(rna1)
print(adt1)
AnnData object with n_obs × n_vars = 1000 × 1000
obs: 'celltype'
layers: None (.X)
AnnData object with n_obs × n_vars = 1000 × 134
obs: 'celltype'
layers: None (.X)
Write the dataset folder. Change each name in quotes marked # <- to one the printout above lists for two of your files, with its prefix, as "obs:celltype".
NAME = "MYMOSAIC_UNSHARED" # <- a new name for your own data
folder = "mydata/" + NAME
celltype = "obs:celltype" # <- the cell-type column of every file
# batch 1: RNA + ADT (adt="obsm:protein" if rna1 holds it)
mtb.io.export_dataset(rna1, folder, rna="X", adt=adt1, labels=celltype,
batch_index=1, category="mosaic", overwrite=True)
# batch 2: RNA + ATAC peaks
mtb.io.export_dataset(rna2, folder, rna="X", atac=atac2, atac_kind="peak",
labels=celltype,
batch_index=2, category="mosaic", overwrite=True)
# batch 3: ADT only
mtb.io.export_dataset(adt3, folder, rna=None, adt="X", labels=celltype,
batch_index=3, category="mosaic", overwrite=True)
mtb.scan("mydata/" + NAME, "mosaic", methods=METHODS)
[scan] 2 of 2 methods have their input files in MYMOSAIC_UNSHARED. 2 of 2 can run on this computer. MYMOSAIC_UNSHARED holds RNA, ADT and ATAC, in batches 1-3. [scan] Cells per file: rna1.h5 1,000, adt1.h5 1,000, rna2.h5 1,000, atac2.h5 1,000, adt3.h5 1,000.
| method | modalities | runnable | reason | env | caveat | |
|---|---|---|---|---|---|---|
| 0 | StabMap | rna1+rna2+adt1+adt3+atac2 | True | scmb_r | ||
| 1 | scMoMaT | rna1+rna2+adt1+adt3+atac2 | True | scmb_torch |
mine = mtb.run("mydata/" + NAME, "mosaic", methods=METHODS,
out_dir="out/" + NAME)
mine.summary
[run] StabMap (mosaic/MYMOSAIC_UNSHARED) ... [run] -> scored (11.1s) ARI 0.395 [run] scMoMaT (mosaic/MYMOSAIC_UNSHARED) ... [run] -> scored (82.2s) ARI 0.375
| method | status | ARI | NMI | ASW | iASW | iF1 | cLISI | ASW_batch | ARI_batch | NMI_batch | GC | iLISI | OCA | ACA | Spec | Sens | F1 | run_sec | caveat | reason | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | StabMap | scored | 0.3945 | 0.5672 | 0.5514 | 0.5357 | 0.3441 | 0.9659 | 0.7003 | 0.7073 | 0.7224 | 0.7590 | 0.1824 | 0.4796 | 0.3813 | 0.9739 | 0.3813 | 0.3211 | 11.1 | ||
| 1 | scMoMaT | scored | 0.3753 | 0.5984 | NaN | NaN | 0.3033 | 0.8186 | NaN | 0.9908 | 0.9835 | 0.9835 | 0.9392 | NaN | NaN | NaN | NaN | NaN | 82.2 |
mine.plot()
6. Every method of this task¶
3 methods run this task. This notebook runs them all. Its 3 environments download 2.5 GB on a computer without a GPU and 5.9 GB on one with a GPU.
Troubleshooting¶
res.summary[res.summary.status != "scored"] lists each method that failed or was skipped. Its reason column ends with the method's error output.
Details
| symptom | fix |
|---|---|
| a method fails on a small dataset | mtb.scan names what the method needs from the data's size in its caveat column |
| batch metrics use the wrong batches | res.rescore(batch=...), with one batch per cell, scores again without running the methods |
Next steps¶
- Run a method, Score an embedding, Load and plot results and Discover methods.
- Look at an embedding draws a method's embedding as a UMAP.
- The interactive explorer has the full benchmark's rankings, with no install needed.