scanpy.pp.normalize_shifted_clr#

scanpy.pp.normalize_shifted_clr(adata, *, alpha=None, layer=None, inplace=True, copy=False)[source]#

Normalize counts with the shifted centered log-ratio (PFlog) transform.

If alpha is not provided, it is estimated from the input matrix. PFlog is then computed as

\[T(x)_i = \log(1 + 4 α x_i) - \frac{1}{D} \sum_{j=1}^D \log(1 + 4 α x_j), \]

which is equivalent to centering \(\log(x_i + 1 / (4 α))\) because the constant \(\log(4 α)\) cancels during CLR centering.

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

✅

scipy.sparse.{csr,csc}_{array,matrix}

✅

✅

Note

CLR centering generally maps zeros to non-zero values, so the resulting matrix is dense even when the input is sparse.

Parameters:
adata AnnData

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

alpha float | None (default: None)

Negative-binomial overdispersion of the dataset (var = μ + α·μ²). If None, it is estimated from the input matrix. A positive numeric value uses that value directly. PFlog applies log1p(4 * alpha * x) before CLR centering.

layer str | None (default: None)

Layer to normalize instead of X.

inplace bool (default: True)

Whether to update adata or return a dictionary with the normalized matrix.

copy bool (default: False)

Whether to modify a copied input object. Not compatible with inplace=False.

Return type:

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

Returns:

Returns a dictionary with the normalized matrix or updates adata, depending on inplace.

Example

>>> import numpy as np
>>> from anndata import AnnData
>>> import scanpy as sc
>>> adata = AnnData(np.array([[1, 2, 30], [4, 50, 6]], dtype="float32"))
>>> sc.pp.normalize_shifted_clr(adata, alpha=0.5)
>>> np.allclose(adata.X.sum(axis=1), 0, atol=1e-5)
True