classify

classify ¶

classify(
    data,
    pos=None,
    neg=None,
    classifyLabel="passed_classify",
    failedLabel="failed_classify",
    phenotype=None,
    subclassifyPhenotype=None,
    threshold=0.5,
    collapseFailed=True,
    label="classify",
    showPhenotypeLabel=False,
    verbose=True,
    outputDir=None,
    sdataTable=None,
)

Label cells by positive and negative marker thresholds.

A cell passes when it is at or above threshold for every marker in pos and below it for every marker in neg. Passing cells get classifyLabel; the rest get failedLabel, or keep their existing phenotype when collapseFailed=True.

Marker values are read from .raw.X when it exists, otherwise .X, so run sp.pp.rescale first if you want 0.5 to mean positive.

phenotype plus subclassifyPhenotype restricts the rule to cells that already carry particular labels — the way to split an existing population without touching the rest.

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
`pos`	`str \| list`	Markers a cell must be positive for.	`None`
`neg`	`str \| list`	Markers a cell must be negative for.	`None`
`classifyLabel`	`str`	Label given to cells that pass.	`'passed_classify'`
`failedLabel`	`str`	Label given to cells that fail, unless `collapseFailed` is `True`.	`'failed_classify'`
`phenotype`	`str`	Column in `obs` holding existing cell type labels, used by `subclassifyPhenotype`, `collapseFailed`, and `showPhenotypeLabel`.	`None`
`subclassifyPhenotype`	`str \| list`	Apply the rule only to cells already labelled one of these in `phenotype`. Everything else fails automatically.	`None`
`threshold`	`float`	The value at which a marker counts as positive.	`0.5`
`collapseFailed`	`bool`	Give failing cells their existing `phenotype` label instead of `failedLabel`, so the output stays a complete phenotype column. Requires `phenotype`.	`True`
`label`	`str`	Column in `obs` the result is written to.	`'classify'`
`showPhenotypeLabel`	`bool`	Label passing cells `"<existing phenotype>-<classifyLabel>"` rather than just `classifyLabel`, keeping the provenance visible.	`False`
`verbose`	`bool`	Print progress messages.	`True`
`outputDir`	`str`	Directory to write the updated object to. With `None` the object is returned instead.	`None`
`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 `obs[label]` set. `None` when `outputDir` is given.

Example

# Pull out one population.
adata = sp.tl.classify(
    adata, pos=["CD3", "CD8"], neg=["FOXP3"],
    classifyLabel="CD8 T cell", label="cd8",
)

# Split an existing phenotype without disturbing the others.
adata = sp.tl.classify(
    adata,
    pos=["PD1"],
    phenotype="phenotype",
    subclassifyPhenotype=["Treg"],
    classifyLabel="PD1+",
    collapseFailed=True,
    showPhenotypeLabel=True,
    label="phenotype_refined",
)