rescale

rescale ¶

rescale(
    data,
    gate=None,
    log=True,
    imageId="imageid",
    verbose=True,
    randomState=0,
    gmmComponents=3,
    outputDir=None,
    layer="raw",
    rescaleMethod="minmax",
    streamData=False,
    sdataTable=None,
)

Rescale every marker to a 0-1 scale centred on its gate.

Raw intensities are not comparable between markers or between images: a CD45 value of 8000 might be strongly positive in one slide and background in the next. Rescaling maps each marker's gate to exactly 0.5, so a single threshold works everywhere.

Two scaling methods:

'minmax' maps values below the gate onto [0, 0.5] and values above onto [0.5, 1], linearly within each half.
'sigmoid' applies a logistic curve with the gate at its midpoint, which is smoother but compresses the extremes.

Gates come from one of three places, in order of precedence: the gate argument, pre-computed gates in uns['gates'], and otherwise a Gaussian Mixture Model fitted per marker per image. GMM fitting is parallelised across a ThreadPoolExecutor; gate lookup uses Polars.

Whichever route is taken, the gates end up in uns['gates'] (markers as rows, images as columns) so a run can be reproduced or hand-corrected.

Parameters:

Name	Type	Description	Default
`data`	`(AnnData \| SpatialData \| str, required)`	The cell table. An `AnnData`, a path to an `.h5ad` file, a `SpatialData` object, or a path to a `.zarr` SpatialData store.	required
`gate`	`str \| DataFrame \| DataFrame`	Manual gates. A path to a CSV, or the table itself, with markers in the first column and one column of gate values per image. A single value column is applied to every image. Overrides `uns['gates']`.	`None`
`log`	`bool`	Apply `log1p` to the selected layer before gating. Leave this on for raw intensities.	`True`
`imageId`	`str`	Column in `obs` holding image identifiers. Gates are fitted per image.	`'imageid'`
`verbose`	`bool`	Print progress messages.	`True`
`randomState`	`int`	Seed for the GMM, so automatic gates are reproducible.	`0`
`gmmComponents`	`int`	Number of components in the Gaussian Mixture Model.	`3`
`outputDir`	`str`	Directory to write the updated object to. With `None` the object is returned instead.	`None`
`layer`	`str`	Which matrix to rescale. `'raw'` uses `.raw.X`, any other string names a key in `.layers`.	`'raw'`
`rescaleMethod`	`str`	`'minmax'` or `'sigmoid'`.	`'minmax'`
`streamData`	`bool`	Run out of core against an `.h5ad` path with CAP-AnnData. Requires `data` to be a path; the file is updated in place and `None` is returned.	`False`
`sdataTable`	`str`	Which `SpatialData` table to work on.	`None`

Returns:

Name	Type	Description
`adata`	`AnnData \| SpatialData \| None`	The updated object with rescaled values in `.X` and the gates used in `uns['gates']`. `None` in streaming mode.

Example

# Automatic gates from a GMM.
adata = sp.pp.rescale(adata)
adata.uns["gates"]

# Manual gates from a CSV, one column per image.
adata = sp.pp.rescale(adata, gate="manual_gates.csv")

# Check the result: every marker should straddle 0.5.
sp.pl.distPlot(adata, vline=0.5)

# Out of core.
sp.pp.rescale("big.h5ad", gate="manual_gates.csv", streamData=True)