Scanpy Documentation

Scanpy is a scalable Python toolkit designed for analyzing single-cell gene expression data. It is built to work jointly with anndata and is capable of efficiently handling datasets exceeding one million cells.

Key features include:

• Preprocessing
• Visualization
• Clustering
• Trajectory inference
• Differential expression testing

Note on Large Datasets: For datasets that exceed available memory, many Scanpy functions are compatible with dask, though this feature is currently considered experimental.

The scanpy.queries module provides utility functions to assist with single-cell data annotation and enrichment tasks. Key capabilities include:

• biomart_annotations: Retrieve annotations from Ensembl BioMart.
• gene_coordinates: Fetch genomic coordinates for genes.
• mitochondrial_genes: Identify mitochondrial genes in a dataset.
• enrich: Perform functional enrichment analysis.

The scanpy.metrics module provides collections of measurements used to evaluate the results of single-cell analysis workflows (such as clustering or spatial patterns).

Available metric modules include:

• scanpy.metrics.modularity: Measures the strength of division of a network into modules.
• scanpy.metrics.confusion_matrix: Evaluates classification performance by comparing predicted labels against ground truth.
• scanpy.metrics.gearys_c: A measure of spatial autocorrelation.
• scanpy.metrics.morans_i: A measure of spatial autocorrelation.

The scanpy.external module contains wrappers categorized into the following functional areas:

• preprocessing: Tools for data cleaning and preparation.
• tools: Wrappers for various single-cell analysis algorithms.
• plotting: External visualization utilities.
• exporting: Tools for exporting data to different formats.

The scanpy.pl module is used for visualizing single-cell data. It largely parallels the scanpy.tl (tools) and scanpy.pp (preprocessing) modules; for most tools and many preprocessing functions, a corresponding plotting function exists with the same name.

Many functions support multiple backends (e.g., HoloViews and matplotlib). For global visual configurations, refer to the settings section of the documentation.

The scanpy.pp module contains functions for transforming the data matrix. Unlike scanpy.tl (tools), preprocessing functions typically perform basic transformations on the data matrix (such as normalization, scaling, or filtering) rather than returning interpretable annotations.

Common tasks include:

• Filtering cells and genes
• Normalization and log transformation
• Identifying highly variable genes
• Batch effect correction and data integration
• Doublet detection
• Computing neighbor graphs

The Scanpy workflow involves sequential calls to analysis tools located in the sc.tl module, which operate on an anndata.AnnData object. These tools typically add annotations to the expression matrix X. For most analysis tools, there is a corresponding plotting function in the sc.pl module.

In-place operations: By default, Scanpy tools operate inplace on the adata object and return None to facilitate memory efficiency. If you need to preserve the original object and receive a new copy, pass copy=True or inplace=False to the function.

Scanpy uses specific PEP 440 naming conventions for non-stable releases:

• Pre-releases: Versions formatted like 1.7.0rc1 or 1.7.0rc2.
• Development versions: Versions formatted like 1.8.0.dev0. These may include a commit hash as a local version identifier, for example: 1.8.0.dev2+g00ad77b.

When building tools or workflows with Scanpy, you should only rely on the documented Public API.

Scanpy does not guarantee the stability of its internal APIs (e.g., functions or arguments that are not explicitly documented in the official API section). Using internal modules—even if they do not have a leading underscore—is not officially supported and may break in future updates.

If you find a feature in the internal API that you need for your work, it is encouraged to open an issue to request that the feature be exported to the public API.