scanpy.pp.calculate_qc_metrics(adata, *, expr_type='counts', var_type='genes', qc_vars=(), percent_top=(50, 100, 200, 500), layer=None, use_raw=False, inplace=False, parallel=None)

Calculate quality control metrics.

Calculates a number of qc metrics for an AnnData object, see section Returns for specifics. Largely based on calculateQCMetrics from scater [McCarthy17]. Currently is most efficient on a sparse CSR or dense matrix.

adata : AnnDataAnnData

Annotated data matrix.

expr_type : strstr

Name of kind of values in X.

var_type : strstr

The kind of thing the variables are.

qc_vars : Collection[str]Collection[str]

Keys for boolean columns of .var which identify variables you could want to control for (e.g. “ERCC” or “mito”).

percent_top : Collection[int]Collection[int]

Which proportions of top genes to cover. If empty or None don’t calculate. Values are considered 1-indexed, percent_top=[50] finds cumulative proportion to the 50th most expressed gene.

layer : str, NoneOptional[str]

If provided, use adata.layers[layer] for expression values instead of adata.X.

use_raw : boolbool

If True, use adata.raw.X for expression values instead of adata.X.

inplace : boolbool

Whether to place calculated metrics in adata’s .obs and .var.

parallel : bool, NoneOptional[bool]

Whether to force parallelism. Otherwise usage of paralleism is based on compilation time and sample size heuristics.

Return type

Tuple[DataFrame, DataFrame], NoneOptional[Tuple[DataFrame, DataFrame]]


Depending on inplace returns calculated metrics (pd.DataFrame) or updates adata’s obs and var.

Observation level metrics include:


E.g. “total_genes_by_counts”. Number of genes with positive counts in a cell.


E.g. “total_counts”. Total number of counts for a cell.

pct_{expr_type}_in_top_{n}_{var_type} - for n in percent_top

E.g. “pct_counts_in_top_50_genes”. Cumulative percentage of counts for 50 most expressed genes in a cell.

total_{expr_type}_{qc_var} - for qc_var in qc_vars

E.g. “total_counts_mito”. Total number of counts for variabes in qc_vars.

pct_{expr_type}_{qc_var} - for qc_var in qc_vars

E.g. “pct_counts_mito”. Proportion of total counts for a cell which are mitochondrial.

Variable level metrics include:


E.g. “total_counts”. Sum of counts for a gene.


E.g. “mean counts”. Mean expression over all cells.


E.g. “n_cells_by_counts”. Number of cells this expression is measured in.


E.g. “pct_dropout_by_counts”. Percentage of cells this feature does not appear in.


Calculate qc metrics for visualization.

>>> adata = sc.datasets.pbmc3k()
>>> sc.pp.calculate_qc_metrics(adata, inplace=True)
>>> sns.jointplot(
        "log1p_total_counts", "log1p_n_genes_by_counts",
        data=adata.obs, kind="hex"