log1p

log1p ¶

log1p(
    data,
    targetLayer="log",
    outputDir=None,
    chunk_size=10000,
    maxWorkers=None,
    verbose=True,
    streamData=False,
    sdataTable=None,
)

Log-transform the expression matrix into a layer.

Applies log1p to .raw.X and stores the result in layers[targetLayer], so the original values stay available. Intensities from imaging are heavily right-skewed; most visualisation and clustering behaves better on the log scale.

The transform runs in row chunks across a ThreadPoolExecutor, and in streaming mode each chunk is read, transformed, and written without the whole matrix ever being resident.

An existing layer of the same name is overwritten.

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
`targetLayer`	`str`	Name of the layer the transformed matrix is written to.	`'log'`
`outputDir`	`str`	Directory to write the updated object to. With `None` the object is returned instead.	`None`
`chunk_size`	`int`	Rows per chunk. Lower it if memory is tight.	`10000`
`maxWorkers`	`int`	Threads to transform with. Defaults to `max(1, cpu_count() - 1)`.	`None`
`verbose`	`bool`	Print progress messages and warnings.	`True`
`streamData`	`bool`	Run out of core against an `.h5ad` path with CAP-AnnData. Requires `data` to be a path.	`False`
`sdataTable`	`str`	Which `SpatialData` table to work on.	`None`

Returns:

Name	Type	Description
`adata`	`AnnData \| SpatialData \| None`	The updated object with `layers[targetLayer]` set. `None` in streaming mode.

Example

adata = sp.pp.log1p(adata)
sp.pl.heatmap(adata, groupBy="phenotype", layer="log")

# Out of core, on a large file.
sp.pp.log1p("big.h5ad", streamData=True, chunk_size=50000)