rapids_singlecell.pp.normalize_pearson_residuals#

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

Applies analytic Pearson residual normalization [LBK21].

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.

Parameters:
adata AnnData

AnnData object

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 normalize, e.g. A.X, A.layers['counts'] or A.obsm['x']. Strings are resolved by anndata.acc.AdAcc.resolve(), e.g. 'layers.counts'.

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

Where to write the result, e.g. A.layers['k'] (or 'layers.k'). If True, the result is returned instead of written. If False, it is written to the place use reads from.

Return type:

AnnData | ndarray | None

Returns:

The normalized matrix if out=True. Otherwise writes it to out and the settings to .uns['pearson_residuals_normalization'] (or .uns[k] for out=A.layers[k]).