foldChange

foldChange ¶

foldChange(
    data,
    fromGroup,
    toGroup=None,
    imageId="imageid",
    phenotype="phenotype",
    normalize=True,
    subsetPhenotype=None,
    label="foldchange",
    verbose=True,
    outputDir=None,
    streamData=False,
    sdataTable=None,
)

Fold change in cell-type abundance between samples.

Counts each phenotype per sample, normalises by the sample's total cell count when normalize=True, and divides every target group by the reference group. Significance comes from a Fisher exact test on the raw counts.

Two tables are written: uns[label + "_fc"] holds the fold changes and uns[label + "_pval"] the p-values, both group x phenotype. Plot them with sp.pl.foldChange.

Normalisation matters here. Without it, a sample with twice as many cells looks enriched for everything.

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
`fromGroup`	`(str \| list, required)`	The reference sample(s) — the denominator of every ratio.	required
`toGroup`	`str \| list`	The sample(s) to compare against the reference. `None` compares every group that is not in `fromGroup`.	`None`
`imageId`	`str`	Column in `obs` holding the sample or ROI identifiers being compared.	`'imageid'`
`phenotype`	`str`	Column in `obs` holding the cell type labels being counted.	`'phenotype'`
`normalize`	`bool`	Divide each group's counts by its total cell number before taking the ratio. Leave this on unless the groups are already the same size.	`True`
`subsetPhenotype`	`list`	Restrict the analysis to these cell types.	`None`
`label`	`str`	Prefix for the two `uns` keys, `label + "_fc"` and `label + "_pval"`.	`'foldchange'`
`verbose`	`bool`	Print progress messages.	`True`
`outputDir`	`str`	Directory to write the updated object to. With `None` the object is returned instead.	`None`
`streamData`	`bool`	Run out of core against an `.h5ad` path with CAP-AnnData, reading only the sections this function needs and writing back only what it changes. 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. Ignored for `AnnData` input, and optional when the store has exactly one table.	`None`

Returns:

Name	Type	Description
`adata`	`AnnData \| SpatialData \| None`	The updated object with `uns[label + "_fc"]` and `uns[label + "_pval"]`. `None` in streaming mode.

Example

adata = sp.tl.foldChange(adata, fromGroup="control", phenotype="phenotype")
adata.uns["foldchange_fc"]
adata.uns["foldchange_pval"]

sp.pl.foldChange(adata, method="heatmap")

# Two named arms only, immune cell types only.
adata = sp.tl.foldChange(
    adata,
    fromGroup="untreated",
    toGroup=["treated_day7", "treated_day21"],
    subsetPhenotype=["Treg", "NK cells", "Dendritic cells"],
)