mantispy.tl.fit_cell_cycle#

mantispy.tl.fit_cell_cycle(adata, key='Metadata_DNAContent', reference='negcon', qc_features=None, layer=None, key_added='cell_cycle', copy=False)[source]#

Fit a cell-cycle clock on the reference cells’ DNA content.

The reference cells’ DNA content is modelled as a 2N peak (G1), a 4N peak (G2M) and S cells between them, each at the position the measurement puts it, plus a flat density for cells off the cycle. The fractions of the three phases are turned into a position in the cycle with the age distribution of an exponentially growing population (ergodic rate analysis, [Kafri et al., 2013]). Position 0 is the start of G1 and 1 is division. Inside S, DNA content places a cell precisely. Inside the 2N and 4N plateaus it does not, and project_cell_cycle() reports the whole plateau as the cell’s uncertainty instead of inventing an order.

The fit first checks that the reference cycles: its DNA content must show a 2N peak, a separate 4N peak and a continuous S population between them. A population that fails, such as an arrested one or a stain that does not resolve the 4N peak, gets a model marked as failed, and projecting it gives NaN.

Parameters:
adata AnnData

Object-resolution object carrying the output of dna_content().

key str (default: 'Metadata_DNAContent')

obs column holding the DNA content, in doublings of the G1 peak.

reference str | None (default: 'negcon')

The cells to fit on: "negcon" for the negative controls, the name of a boolean obs column, or None for every cell.

qc_features tuple[str, str] | None (default: None)

The nuclear area and solidity features, as a pair. With them, the model learns from the reference how small, how irregular and how dim, per amount of DNA, a nucleus may be, and project_cell_cycle() flags nuclei beyond that. None checks no shape.

layer str | None (default: None)

Layer to read qc_features from, or None for X. The model records it, and projection reads the same layer.

key_added str (default: 'cell_cycle')

Key the model is written under in uns["mantispy"].

copy bool (default: False)

Return a modified copy instead of mutating in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes uns["mantispy"][key_added]: the DNA key, whether the reference passed the check and the check measures, the measured 2N and 4N peaks and the 2N peak width sd. A model that passed also holds the reference fractions in G1, S and G2M, the cycle positions where G1, S and G2M begin and end as edges, and the off_cycle weight. With qc_features it holds a qc entry with the features and the cutoffs on log2 area, solidity and log2 DNA per area, and the layer they were read from.

Raises:

  • KeyError – obs has no column key; run dna_content() first. Or a qc_features feature is missing.

  • ValueError – The reference holds too few cells with a DNA content to fit on.

Notes

The check asks for a 4N peak between 0.6 and 1.4 doublings, at least a twentieth the height of the 2N peak. It asks for a valley between the peaks no higher than nine tenths of the 4N peak, a density across S of at least a tenth of the 4N peak, and at least 3% of the reference between 1.25 and 1.75 times the 2N amount of DNA.

The model assumes that DNA content is flat through G1 and through G2M, that DNA is replicated at a steady rate through S, and that the reference grows in steady state, with every phase taking a fixed share of the cycle. It cannot tell G0 from G1, nor mitosis from G2, since both pairs share a DNA content.

See also

phase_order() for an experimental order within a phase from the other features. Where cells sit in the cycle for a worked example, and How the cell-cycle model works for how the model works, step by step.