mantispy.pl.cell_cycle_clock

mantispy.pl.cell_cycle_clock(adata, key='cell_cycle', color=None, groups=None, radius=None, groupby=None, ncols=None, ax=None, size=None, alpha=None, width=None, palette=None, cmap=None, vmin=None, vmax=None, na_color='lightgray', legend_loc='right margin', legend_fontsize=6, frameon=False, rim=True, seed=0, kind='cells', bandwidth=0.02, reference=None, **kwargs)

Cells on a ring, placed by angle at a cycle position drawn from their posterior.

The angle is a cycle position drawn from each cell’s posterior from project_cell_cycle(), seeded for a stable figure, so the ring fills rather than stacking on the medians. Position 0 is at the top and the angle runs clockwise, so G1 starts at twelve o’clock and a cell comes back to the top as it divides. Cells sit in a band around a ring, spread radially at random within width, or, with radius, on an annulus whose radius follows an obs column such as the DNA content.

DNA content orders cells only through S, since it is flat at 2N through G1 and at 4N through G2M. The S arc therefore places each cell from its own DNA, while in the G1 and G2M arcs the angle follows the reference’s age distribution, where a cell is more likely to sit early. Those two arcs are shaded and labelled as the population prior. When obs[key + "_" + phase + "_order"] holds an order from phase_order(), the cells of that phase sit on their arc by that order instead, and the arc is labelled as the experimental order. Read the clock by where a colour concentrates, not as a fine order within a prior arc. Cells off the cycle have no position and are left out.

With kind="rings" the same positions are smoothed into one density per category of color, each on its own ring in the order of groups, the first outermost, so where in the cycle the cells of each group concentrate reads from the ring’s height. kind="ridge" draws the same densities as rows over a straight cycle axis, which stays readable for many groups. Densities share one scale within a panel and across panels with the same number of rings or rows, and each density reads against its own dashed line, which marks the height of cells spread evenly over the cycle. A category with too few cells in a panel to give a density gets none there, with a warning. Within a prior arc the shape of a density follows the prior, so compare how much of each group sits in an arc rather than its shape there.

The colour and legend parameters follow scanpy.pl.embedding().

Parameters:

adata AnnData

Single-cell object project_cell_cycle() has run on.

key str (default: 'cell_cycle')

The key_added prefix project_cell_cycle() wrote.

color str | None (default: None)

What colours the cells: None for the phase; "position" or key + "_position" for the cycle position on a cyclic colour map; another obs column, categorical or numeric; or a feature. Cells with a position but no value are drawn in na_color.

groups list[str] | str | None (default: None)

With a categorical color, colour only the named categories, each with its own colour and a legend, and draw every other cell in na_color behind them. None colours every category.

radius str | None (default: None)

An obs column mapped to the radius, so the ring becomes an annulus, its inner edge the column’s 2nd percentile and its outer edge the 98th. None keeps the ring.

groupby str | None (default: None)

obs column whose groups each get their own clock on a shared layout, colour scale and legend, or None for one clock.

ncols int | None (default: None)

Clocks per row when groupby is given, or None for up to five per row.

ax Axes | None (default: None)

Axes to draw a single clock on, or None for a new figure.

size float | None (default: None)

Marker area; None scales it with the number of cells, as scanpy does.

alpha float | None (default: None)

Marker opacity; None for a default that depends on color.

width float | None (default: None)

Thickness of the band the cells sit in, as a fraction of the ring’s radius. A wider band spreads a crowded arc out. None gives 0.3 for the ring and 0.6 for the radius annulus.

palette Mapping[str, Any] | Sequence[Any] | str | None (default: None)

Colours for a categorical color: a mapping from category to colour, a list of colours taken in order, or a colour map name. Categories it leaves out keep the phase colours or a default.

cmap str | None (default: None)

Colour map for a numeric or feature color; defaults to twilight for the cyclic position and viridis otherwise.

vmin float | str | None (default: None)

Lower end of a numeric colour scale: a number, or "pN" for the N-th percentile of the drawn values. None gives the 2nd percentile.

vmax float | str | None (default: None)

Upper end, read the same way; None gives the 98th percentile.

na_color Any (default: 'lightgray')

Colour of cells with a position but no value, and of the cells outside groups.

legend_loc str | None (default: 'right margin')

"right margin" for a legend beside the clock, "on data" to write each category at the angle where its cells concentrate, or None for no legend.

legend_fontsize float (default: 6)

Font size of the legend or the labels on the clock.

frameon bool (default: False)

Draw a frame around each clock.

rim bool (default: True)

Draw the phase arcs outside the ring.

seed int (default: 0)

Seed for the drawn positions, the radial spread and the draw order.

kind str (default: 'cells')

"cells" for one marker per cell, "rings" for one density ring per category of color, or "ridge" for one density row per category. With color=None the densities draw one curve over every cell, filled by phase. radius, size, alpha, width, the colour scale and kwargs apply to "cells" only.

bandwidth float (default: 0.02)

Standard deviation of the smoothing kernel of "rings" and "ridge", as a fraction of the cycle.

reference str | None (default: None)

A category, such as the controls, whose density becomes the dashed line of every ring and row instead of the even spread, so a group’s arrest shows where it rises above the reference. It is a category of color, drawn first, or of groupby when color is None. A panel with too few reference cells compares to the reference cells of every panel.

kwargs Any

Passed to the scatter, overriding its defaults; norm sets a numeric scale.

Return type:

Axes | None

Returns:

The axes when the caller passed ax, else None because the plot then owns the figure it created.

Raises:

• KeyError – obsm has no key + "_quantiles", or color or radius names nothing.

• ValueError – color is both an obs column and a feature, groups is given without a categorical color, a name in groups is not a category of color, ax is given with groupby, legend_loc is not one of its options, vmin or vmax is a string that is not a percentile, kind is not one of its options, kind draws densities of a numeric color, bandwidth is not positive, or reference is not a category of color or groupby.