scanpy.pp.normalize_total

scanpy.pp.normalize_total(adata, *, target_sum=None, exclude_highly_expressed=False, max_fraction=0.05, use=None, out=False, key_added=None, layer=None, obsm=None, inplace=True, copy=False)

Normalize counts per cell.

Normalize each cell by total counts over all genes, so that every cell has the same total count after normalization. If choosing target_sum=1e6, this is CPM normalization.

If exclude_highly_expressed=True, very highly expressed genes are excluded from the computation of the normalization factor (size factor) for each cell. This is meaningful as these can strongly influence the resulting normalized values for all other genes [Weinreb et al., 2017].

Similar functions are used, for example, by Seurat [Satija et al., 2015], Cell Ranger [Zheng et al., 2017] or SPRING [Weinreb et al., 2017].

Array type support

Array type	supported	… experimentally in dask Array
numpy.ndarray	✅	✅
scipy.sparse.csr_array / csr_matrix	✅	✅
scipy.sparse.csc_array / csc_matrix	❌	❌

Note

When used with a Array in adata.X, this function will have to call functions that trigger .compute() on the Array if exclude_highly_expressed is True, or if norm_factor is written.

Parameters:

adata AnnData

The annotated data matrix of shape n_obs × n_vars. Rows correspond to cells and columns to genes.

target_sum float | None (default: None)

If None, after normalization, each observation (cell) has a total count equal to the median of total counts for observations (cells) before normalization.

exclude_highly_expressed bool (default: False)

Exclude (very) highly expressed genes for the computation of the normalization factor (size factor) for each cell. A gene is considered highly expressed, if it has more than max_fraction of the total counts in at least one cell. The not-excluded genes will sum up to target_sum. Providing this argument when adata.X is a Array will incur blocking .compute() calls on the array.

max_fraction float (default: 0.05)

If exclude_highly_expressed=True, consider cells as highly expressed that have more counts than max_fraction of the original total counts in at least one cell.

use LayerAcc | MultiAcc | str | None (default: None)

Which matrix to normalize. Given by an accessor, e.g. A.X, A.layers['counts'] or A.obsm['pca']. strs are anndata.acc.AdAcc.resolve()d, e.g. 'layers.counts'.

layer str | None (default: None)

Deprecated since version 1.13.0: Use use/out instead.

A key of layers, i.e. layer='k' is use=A.layers['k'].

obsm str | None (default: None)

Deprecated since version 1.13.0: Use use/out instead.

A key of obsm, i.e. obsm='k' is use=A.obsm['k'].

out LayerAcc | MultiAcc | str | NormalizeTotalOut | bool (default: False)

Where to write the outputs. A single accessor writes normalized to it and names the others after its key k: k in kinds of places no other output goes to, else k_{name}, e.g. .obsp['k_distances'] next to .obsp['k']. Outputs that aren’t written by default stay unwritten. A mapping from output names to accessors writes only the outputs it names, each to a different place, e.g. {'normalized': A.layers['normalized']}. strs are anndata.acc.AdAcc.resolve()d. If True, they are returned as a NormalizeTotalResult instead of written. If False, they are written to their default locations. The outputs are:

normalized

The normalized matrix. By default written to the place use reads from.

norm_factor

The normalization factor of each cell. By default not written.

key_added str | None (default: None)

Deprecated since version 1.13.0: Use out instead.

key_added='k' is out={'normalized': <use>, 'norm_factor': A.obs['k']}.

inplace bool (default: True)

Deprecated since version 1.13.0: Use out=True instead of inplace=False.

inplace=False is out=True.

copy bool (default: False)

Deprecated since version 1.13.0: Copy adata before calling this function instead.

Whether to return a modified copy instead of modifying adata in place.

Return type:

AnnData | NormalizeTotalResult | dict[str, ndarray] | None

Returns:

Returns the outputs as a NormalizeTotalResult if out=True, else None. The deprecated inplace=False returns them as a dict instead.

Example

>>> import sys
>>> from anndata import AnnData
>>> import scanpy as sc
>>> sc.settings.verbosity = "info"
>>> sc.settings.logfile = sys.stdout  # for doctests
>>> np.set_printoptions(precision=2) and None
>>> adata = AnnData(
...     np.array(
...         [
...             [3, 3, 3, 6, 6],
...             [1, 1, 1, 2, 2],
...             [1, 22, 1, 2, 2],
...         ],
...         dtype="float32",
...     )
... )
>>> adata.X
array([[ 3.,  3.,  3.,  6.,  6.],
       [ 1.,  1.,  1.,  2.,  2.],
       [ 1., 22.,  1.,  2.,  2.]], dtype=float32)
>>> X_norm = sc.pp.normalize_total(adata, target_sum=1, out=True).normalized
normalizing counts per cell
    finished (0:00:00)
>>> X_norm
array([[0.14, 0.14, 0.14, 0.29, 0.29],
       [0.14, 0.14, 0.14, 0.29, 0.29],
       [0.04, 0.79, 0.04, 0.07, 0.07]], dtype=float32)
>>> X_norm = sc.pp.normalize_total(
...     adata,
...     target_sum=1,
...     exclude_highly_expressed=True,
...     max_fraction=0.2,
...     out=True,
... ).normalized
normalizing counts per cell
The following highly-expressed genes are not considered during normalization factor computation:
['1', '3', '4']
    finished (0:00:00)
>>> X_norm
array([[ 0.5,  0.5,  0.5,  1. ,  1. ],
       [ 0.5,  0.5,  0.5,  1. ,  1. ],
       [ 0.5, 11. ,  0.5,  1. ,  1. ]], dtype=float32)