mtopic.pp.clr

Contents

mtopic.pp.clr#

mtopic.pp.clr(mdata, mod, copy=False, from_layer=None, create_counts_layer=True, counts_layer='counts', pseudocount=1e-06)#

Perform Centered Log-Ratio (CLR) normalization on a modality in a MuData object.

This function applies CLR normalization to the specified modality within a MuData object. CLR normalization is widely used for compositional data, such as single-cell protein counts. It calculates a per-cell scaling factor derived from the mean of log1p(counts) across features, rescales counts by this factor, and applies a log transformation.

By default, this function creates layers[“counts”] (if it does not exist) to preserve raw counts, and then overwrites the modality .X matrix with CLR-transformed values.

Parameters:

  • mdata (muon.MuData) – A MuData object containing multimodal single-cell data.

  • mod (str) – The modality to which CLR normalization will be applied (e.g., ‘prot’).

  • copy (bool, optional) – If True, creates a copy of the MuData object, and the normalization is applied to the copy. If False, the normalization is performed in-place on the original object. Default is False.

  • from_layer (str, optional) – Optional layer name used as input for CLR. If None, uses .X as input. Default is None. Note: regardless of from_layer, the CLR-transformed matrix is written to .X.

  • create_counts_layer (bool, optional) – If True and layers[counts_layer] does not exist, store a copy of the current .X matrix in layers[counts_layer] before overwriting .X. Default is True.

  • counts_layer (str, optional) – Name of the layer used to store raw counts. Default is “counts”.

  • pseudocount (float, optional) – Small value added to the per-cell scaling factor to avoid division by zero. Default is 1e-6.

Returns:

If copy is True, returns a new MuData object with CLR-transformed .X. If copy is False, returns None and modifies the object in-place.

Return type:

muon.MuData or None

Example:
import mtopic

# Load a MuData object
mdata = mtopic.read.h5mu("path/to/file.h5mu")

# CLR-transform protein counts in-place (stores raw counts in layers["counts"])
mtopic.pp.clr(mdata, mod="prot")

# CLR-transform using a layer as input, but still write output to .X
mtopic.pp.clr(mdata, mod="prot", from_layer="counts")

# Return a copy
mdata_clr = mtopic.pp.clr(mdata, mod="prot", copy=True)
Contents