scanpy.experimental.pp.normalize_pearson_residuals#

scanpy.experimental.pp.normalize_pearson_residuals(adata, *, theta=100, clip=None, check_values=True, use=None, out=False, layer=None, obsm=None, inplace=True, copy=False)[source]#

Apply analytic Pearson residual normalization, based on Lause et al. [2021].

The residuals are based on a negative binomial offset model with overdispersion theta shared across genes. By default, residuals are clipped to sqrt(n_obs) and overdispersion theta=100 is used.

Expects raw count input. Cells or genes with zero total counts receive zero residuals, including when the entire input consists of zeros.

Parameters:
adata AnnData

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

theta float (default: 100)

The negative binomial overdispersion parameter theta for Pearson residuals. Higher values correspond to less overdispersion (var = mean + mean^2/theta), and theta=np.inf corresponds to a Poisson model.

clip float | None (default: None)

Determines if and how residuals are clipped:

  • If None, residuals are clipped to the interval [-sqrt(n_obs), sqrt(n_obs)], where n_obs is the number of cells in the dataset (default behavior).

  • If any scalar c, residuals are clipped to the interval [-c, c]. Set clip=np.inf for no clipping.

check_values bool (default: True)

If True, checks if counts in selected layer are integers as expected by this function, and return a warning if non-integers are found. Otherwise, proceed without checking. Setting this to False can speed up code for large datasets.

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

Which matrix to use as input. 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 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 instead.

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

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

Where to write the result, e.g. A.layers['scaled']. strs are anndata.acc.AdAcc.resolve()d, e.g. 'layers.scaled'. If True, the result is returned instead of written. If False, it is written to the place use reads from.

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 | ndarray | dict[str, ndarray] | None

Returns:

If out=True, returns the normalized values.

Otherwise, writes them to out (by default where use reads from), and updates adata.uns with the following fields. That .uns entry is named after the key out writes to (e.g. 'k' for out=A.layers['k']), and 'pearson_residuals_normalization' by default. The deprecated inplace=False returns these fields as dictionary with the normalized values in results_dict['X'].

.uns['pearson_residuals_normalization']['theta']

The used value of the overdisperion parameter theta.

.uns['pearson_residuals_normalization']['clip']

The used value of the clipping parameter.

.uns['pearson_residuals_normalization']['computed_on']

Where the residuals were computed on, e.g. "A.layers['counts']" or 'adata.X'.