mantispy.tl.phase_order#

mantispy.tl.phase_order(adata, phase='G2M', model='cell_cycle', reference='negcon', features=None, layer=None, anchor=None, key_added=None, copy=False)[source]#

Experimental: order the cells within one phase from features other than DNA content.

DNA content is flat through G1 and G2M, so project_cell_cycle() cannot order cells within them. This orders them from the other features, without labels. On the reference cells on the cycle, the features are scaled robustly and reduced to their principal components, and a ridge regression of DNA content on those components, fitted on the S cells, gives an S axis. Each feature is weighted by its rank correlation with DNA content in S. The reference cells of phase start at their rank on the S axis, and that rank is smoothed along their nearest-neighbour graph in the weighted space. Each cell of phase then gets the mean order of its nearest reference cells, so a cell’s order depends only on the reference and on the cell, and orders are comparable across objects placed against the same anchor.

The order assumes that whatever changes through S keeps changing in the same direction through phase. It can follow cell size, DNA damage or any other feature that trends through S rather than progress, and nothing label-free tells which. Validate it against a marker of the phase or a paired modality before reading it.

Parameters:
adata AnnData

Object-resolution object carrying the DNA content column the model was fitted on.

phase str (default: 'G2M')

The phase to order: "G1", "S" or "G2M". Cells are assigned to it by the model.

model str | Mapping (default: 'cell_cycle')

Key of a fit_cell_cycle() model in uns["mantispy"], or the model itself.

reference str | None (default: 'negcon')

The cells the order is fitted on: "negcon" for the negative controls, the name of a boolean obs column, or None for every cell. Ignored with anchor.

features Sequence[str] | None (default: None)

The features to order on. None uses every feature except those measured on a DNA stain and the nuclear shape features of the DNA mask, so the order cannot read DNA content back.

layer str | None (default: None)

Layer to read the features from, or None for X. Ignored with anchor, which records its own.

anchor str | Mapping | None (default: None)

An order written by an earlier call, its key in uns["mantispy"] or the entry itself. This object’s cells are then placed against that call’s reference cells instead of fitting new ones.

key_added str | None (default: None)

Key of the order in obs and of its entry in uns["mantispy"]. Defaults to model + "_" + phase + "_order", which cell_cycle_clock() reads.

copy bool (default: False)

Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes obs[key_added], the order of every cell of phase from 0 to 1 and NaN for every other cell, and uns["mantispy"][key_added], holding the phase, the features and layer, their scaling, the principal axes, the S-axis coefficients, the feature weights, and the reference cells’ embedding and order.

Raises:

  • KeyError – The model, its DNA content column or a feature is missing.

  • ValueError – phase is not G1, S or G2M, the model failed its check, or the reference holds fewer than 50 S cells or 50 cells of phase.

Warns:

UserWarning – Every call, since the order needs validating against a marker or a paired modality.

See also

How the cell-cycle model works for each step, and where it worked and where it did not.