scanpy.pp.scale

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](data, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, use=None, out=False, mask=None, copy=False, layer=None, obsm=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](x, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, copy=False, return_mean_std=False, mask=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](x, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, copy=False, return_mean_std=False, mask=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](x, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, copy=False, return_mean_std=False, mask=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](x, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, copy=False, return_mean_std=False, mask=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](x, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, copy=False, return_mean_std=False, mask=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](x, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, copy=False, return_mean_std=False, mask=None, mask_obs=None)

scanpy.pp.scale[A: csr_array | csc_array | csr_matrix | csc_matrix | ndarray | Array](adata, *, zero_center=True (sc.settings.preset='scanpy-v1' – changes in 2.0), max_value=None, use=None, out=False, mask=None, layer=None, obsm=None, mask_obs=None)

Scale data to unit variance and zero mean.

Note

Variance and standard deviation are computed with Bessel’s correction, i.e. dividing by n_obs - 1 (ddof=1), matching numpy.std() with ddof=1 rather than the numpy default of ddof=0 (population variance). The difference is negligible for large n_obs but can matter for small datasets, where it also slightly shifts where max_value clipping takes effect.

Note

Variables (genes) that do not display any variation (are constant across all observations) are retained and (for zero_center==True) set to 0 during this operation. In the future, they might be set to NaNs.

Array type support

Array type	supported	… experimentally in dask Array
numpy.ndarray	✅	✅
scipy.sparse.{csr,csc}_{array,matrix}	✅	✅

Parameters:

data AnnData | A

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

zero_center bool | Default (default: True (sc.settings.preset='scanpy-v1' – changes in 2.0))

If False, omit zero-centering variables, which allows to handle sparse input efficiently. The default will be removed in scanpy 2.0.

max_value float | None (default: None)

Clip (truncate) to this value after scaling. If None, do not clip.

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

Which matrix to scale. 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 | ScaleOut | bool (default: False)

Where to write the outputs. A single accessor writes scaled 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. {'scaled': A.layers['scaled']}. strs are anndata.acc.AdAcc.resolve()d. If True, they are returned as a ScaleResult instead of written. If False, they are written to their default locations. The outputs are:

scaled

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

mean

Means per variable before scaling. By default written to A.var['mean'] (A.var['mean of {mask}'] or A.var['mean with mask'] if mask is given).

std

Standard deviations per variable before scaling. By default written to A.var['std'] (A.var['std of {mask}'] or A.var['std with mask'] if mask is given).

copy bool (default: False)

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

Whether to leave the input unmodified: For AnnData input, return a scaled copy of it.

mask NDArray[bool] | AdRef[Idx2D | int, AnnData] | str | None (default: None)

Restrict both the derivation of scaling parameters and the scaling itself to a certain set of observations. Given by a boolean array or a reference to one, e.g. A.obs['selected']. strs are anndata.acc.AdAcc.resolve()d, e.g. 'obs.selected'. This will transform data from csc to csr format if issparse(data).

mask_obs NDArray[bool] | AdRef[Idx2D | int, AnnData] | str | None (default: None)

Deprecated since version 1.13.0: Use mask instead.

A boolean array, or a column of obs named by a str, i.e. mask_obs='selected' is mask=A.obs['selected'].

Return type:

AnnData | A | ScaleResult | None

Returns:

For array input, returns the scaled matrix. Otherwise, returns the outputs as a ScaleResult if out=True, a copy of adata if copy=True, else None. By default sets the following fields (see out for others):

adata.X | adata.layers[...]numpy.ndarray | scipy.sparse.csr_matrix (dtype float)

Scaled count data matrix, written where use reads from.

adata.var['mean']pandas.Series (dtype float)

Means per gene before scaling.

adata.var['std']pandas.Series (dtype float)

Standard deviations per gene before scaling.