DOCSEARCHbyAlgolia
Submit Docs

scib: Evaluating single-cell data integration methods

repository·main·Indexed 19 days ago

https://github.com/theislab/scib

A Python package for benchmarking atlas-level data integration in single-cell genomics. scib provides tools for preprocessing single-cell datasets using scanpy, running various integration methods via scib.integration, and evaluating results through biological conservation and batch correction metrics in scib.metrics. It supports evaluation across feature space, embedding space, and kNN graph space representations.

Tokens
9.6K
Snippets
50
Records
55
Agent score
64%

What's inside scib

  1. Overview of scib modules and functionality

    main

    The scib package is organized into several modules to handle the single-cell integration workflow using anndata objects:

    • Preprocessing: scib.preprocessing (or scib.pp) contains functions for normalizing, scaling, or batch-aware selection of highly variable genes.
    • Integration: scib.integration (or scib.ig) contains functions for running various integration methods.
    • Metrics: scib.metrics (or scib.me) contains functions for evaluating the results of integration.

    To use the package in Python:

    import scib

  2. Understand data representations in scib

    main

    The scib metrics can evaluate datasets or integration performance using three types of data representations. The choice of representation determines which metrics are applicable:

    1. Feature space: A feature-level expression matrix (e.g., normalized/log-transformed counts or corrected counts from integration).
    2. Embedding space: A PCA of the feature-level expression matrix or an embedding produced by an integration method.
    3. kNN graph space: A k-nearest neighbors (kNN) graph constructed on a PCA or an embedding.

    Metric Applicability Rules:

    • kNN graph space representations can only be evaluated by graph-based metrics.
    • Embedding space representations can be evaluated by embedding-based and graph-based metrics (though graph metrics require constructing a kNN graph first).
    • Feature space representations allow for the computation of embeddings and kNN graphs, making all metrics applicable.

  3. Evaluate integration quality using scib.metrics

    main

    Metrics in scib are used to benchmark scRNA-seq data integration performance. They can be applied to both integrated and unintegrated data and are categorized into two types:

    1. Biological Conservation Metrics: Quantify the integrity of biological aspects (e.g., clusters or feature spaces). Scores are scaled 0 to 1, where higher is better.
    2. Batch Correction Metrics: Quantify how well batches have been removed. Scores are scaled 0 to 1, where higher is better.

    Most metrics require specific preprocessing steps as described in the preprocessing documentation.

  4. Prepare embedding output for evaluation

    main

    Embeddings should be stored in adata.obsm, with the default key being 'X_emb'.

    If a metric requires an embedding, no further preprocessing is needed for the embedding itself. However, if the metric also requires a kNN graph or clustering, you must perform those steps first:

    1. Construct the kNN graph using the embedding (e.g., via scanpy.pp.neighbors).
    2. Perform clustering with an optimized resolution.
    sc.pp.neighbors(adata, use_rep="X_emb")
scib.me.cluster_optimal_resolution(adata, cluster_key="cluster", label_key="celltype")

  5. Manually compile the knn-graph C++ function

    main

    The knn_graph.cpp function is a C++ implementation used for k-nearest neighbor graph construction. If you need to compile it manually, use g++ with the c++11 standard and O3 optimization level to ensure performance.

    g++ -std=c++11 -O3 knn_graph.cpp -o knn_graph.o

  6. Install optional integration method dependencies

    main

    By default, scib is only installed with the packages required for metrics to avoid dependency clashes. To use specific integration methods, you must install their corresponding optional dependencies using pip extras.

    Note for Zsh users: If you are using Zsh, you must wrap the installation command in quotation marks because Zsh treats square brackets as special characters.

    Available extras:

    • bbknn: For using BBKNN
    • scanorama: For using Scanorama

    Examples:

    • Install BBKNN: pip install scib[bbknn]
    • Install Scanorama: pip install scib[scanorama]
    • Install both: pip install scib[bbknn,scanorama]
    # For standard shells
pip install scib[bbknn]

# For Zsh users
pip install 'scib[bbknn]'

  8. Run integration methods with scib.ig

    main

    Integration method functions in scib require a preprocessed anndata object (adata) and the name of the batch column found in adata.obs.

    Note on Naming: The package uses snake_case naming. The deprecated scib.integration.runIntegrationMethod should be replaced with the corresponding function in scib.ig (e.g., scib.ig.scanorama).

    Some methods also require cell type labels from adata.obs.

    # Standard integration call
scib.ig.scanorama(adata, batch="batch")

# Integration requiring cell type labels
scib.ig.scgen(adata, batch="batch", cell_type="cell_type")
scib.ig.scanvi(adata, batch="batch", labels="cell_type")

  9. Prepare kNN graph output for evaluation

    main

    To use graph-based metrics, the kNN graph must be stored in the anndata object at the following locations:

    • adata.obsp['neighbors']
    • adata.obsp['connectivities']

    Some metrics also require cluster assignments to compare against known cell labels. To ensure representative cluster assignments, it is recommended to use resolutions optimized to the hierarchy of the cell labels using scib.me.cluster_optimal_resolution.

    scib.me.cluster_optimal_resolution(adata, cluster_key="cluster", label_key="celltype")