markers#

API pages include interactive (HTML) plots that would possibly not render correctly on a mobile device.

markers(data: AnnData, groups: Sequence[str] | None = None, *, key: str = 'rank_genes_groups', n_genes: int = 20, mapping: FeatureSpec | None = None, text_color: str = '#1f1f1f', text_size: float = 4.0, fontface: str = 'bold', angle: float = 90.0, rank_color: bool = False, line: bool = False, line_color: str = '#3f3f3f', line_size: float = 0.4, line_alpha: float = 0.6, line_kwargs: dict | None = None, variable_column: str = 'variable', score_column: str = 'score', rank_column: str = 'rank', group_column: str = 'group', interactive: bool = False, share_labels: bool = True, share_axis: bool = False, layers: Sequence[FeatureSpec | LayerSpec] | FeatureSpec | LayerSpec | None = None, ncol: int | None = 3, sharex: str | None = None, sharey: str | None = None, widths: list[float] | None = None, heights: list[float] | None = None, hspace: float | None = None, vspace: float | None = None, fit: bool | None = None, align: bool | None = None, guides: str = 'auto', **text_kwargs) → SupPlotsSpec#

Grid of ranked genes per group.

Parameters:

  • data (AnnData) – The single-cell data object holding the precomputed differential expression ranking.

  • groups (Sequence[str] | None, default None) – Subset of groups to plot, one panel per group. None keeps all groups in their stored order.

  • key (str, default 'rank_genes_groups') – The key under which the precomputed ranking is stored on data.

  • n_genes (int, default 20) – Number of top genes to show per panel.

  • mapping (FeatureSpec | None, default None) – Additional aesthetic mappings, the result of aes(). Merged on top of the default aes(x=rank, y=score, label=variable).

  • text_color (str, default '#1f1f1f') – Color of the gene-name text.

  • text_size (float, default 4.0) – Size of the gene-name text.

  • fontface (str, default 'bold') – Font face of the gene-name text (e.g. ‘plain’, ‘bold’, ‘italic’).

  • angle (float, default 90.0) – Rotation angle of the gene-name text, in degrees.

  • rank_color (bool, default False) – Whether to color the gene-name text by rank. When True, the best-ranked gene is pure red, fading toward light gray for the lowest-ranked.

  • line (bool, default False) – Whether to draw a dashed path connecting the genes’ (rank, score) points, showing the score decay across the ranking.

  • line_color (str, default '#3f3f3f') – Color of the dashed score-curve line.

  • line_size (float, default 0.4) – Size (thickness) of the dashed score-curve line.

  • line_alpha (float, default 0.6) – Alpha (opacity) of the dashed score-curve line.

  • line_kwargs (dict | None, default None) – Additional parameters passed to the score-curve geom_path layer.

  • variable_column (str, default 'variable') – Output column name for the gene/feature names.

  • score_column (str, default 'score') – Output column name for the ranking scores.

  • rank_column (str, default 'rank') – Output column name for the per-group rank index (0-based).

  • group_column (str, default 'group') – Output column name for the group label.

  • interactive (bool, default False) – Whether to make the plot interactive.

  • share_labels (bool, default True) – Whether to share axis labels across the grid. If True, only X labels on bottom row and Y labels on left column are shown.

  • share_axis (bool, default False) – Whether to share axes across the grid. If True, only X axis on bottom row and Y axis on left column is shown.

  • layers (Sequence[FeatureSpec|LayerSpec] | FeatureSpec | LayerSpec | None, default None) – Layers to add to all the plots in the grid.

  • ncol (int, default 3) – Number of columns in grid. If None, shows plots horizontally, in one row.

  • sharex (str | None, default None) – Controls sharing of axis limits between subplots in the grid. See lets_plot.gggrid().

  • sharey (str | None, default None) – Controls sharing of axis limits between subplots in the grid. See lets_plot.gggrid().

  • widths (list[float], default None) – Relative width of each column of the grid.

  • heights (list[float], default None) – Relative height of each row of the grid.

  • hspace (float | None, default None) – Cell horizontal/vertical spacing in px.

  • vspace (float | None, default None) – Cell horizontal/vertical spacing in px.

  • fit (bool, default None) – Whether to stretch each plot to match the aspect ratio of its cell.

  • align (bool, default None) – Whether to align inner areas of plots.

  • guides (str, default 'auto') – How guides (legends/colorbars) should be treated in the layout. See lets_plot.gggrid().

  • **text_kwargs – Additional parameters for the geom_text layer of each panel.

Returns:

SupPlotsSpec – Grid of ranked-genes panels, one per group.

Raises:

  • UnsupportedDataTypeError – If data is not a supported single-cell data object.

  • KeyNotFoundError – If the ranking result or a requested group is missing.

  • ValueError – If n_genes is out of range.

  • TypeError – If groups is neither a Sequence of strings nor None.

Notes

Builds one panel per group from a precomputed ranking, placing the top n_genes gene names as text at their (rank, score) position. Each panel is titled “{group} vs. rest”.

Examples

A simple grid of ranked genes per group, with optional score-curve lines.

import scanpy as sc

import cellestial as cl

data = sc.datasets.pbmc68k_reduced()

cl.markers(data, line=True)

Color the gene names by rank.

cl.markers(data, rank_color=True)

Select a subset of groups.

cl.markers(
    data,
    groups=["CD14+ Monocyte", "CD4+/CD25 T Reg", "CD4+/CD45RO+ Memory", "CD34+"],
    ncol=2,
    rank_color=True,
)
On this page