zmap.dotplot — Dotplot Visualization

Publication-ready dotplots for exploring gene expression across cell types, developmental timepoints, and studies.

The module provides two entry points via convenient aliases:

• zmap.dotplot.gene_view → gene_groups_vs_time_and_studies()

• zmap.dotplot.group_view → group_siblings_vs_markers()

Gene-Centric Dotplots

zmap.dotplot.gene_groups_vs_time_and_studies(adata, color, *, groupby='ZMAP_CellType', time_col='time_group_id', study_col='study_id', layer='tpm_log', use_raw=None, detect_threshold=0.0, show=True, cmap='viridis', vmin=0, vmax=None, cbar_title='log(tpm)\\ncounts', add_colorbar=True, s_min=4.0, s_max=60.0, size_zero_for_missing=True, abs_min_cells=10, rel_min_frac=0.01, rel_abs_cap=300, low_support_grey='0.7', low_support_alpha=0.5, cell_size=0.14, middle_gap=0.2, gutter_width=0.8, gutter_pad=0.03, figsize=None, xlabel_rotation=90, title_left='Timepoints', title_right='Studies', show_size_legend=True, size_legend_values=None, size_legend_title=None, size_legend_facecolor='black', cluster_order=['blastomeres', 'ectoderm_progenitor', 'fin_epidermis', 'basal_epidermis', 'ionocytes', 'lens', 'lateral_line', 'olfactory', 'otic', 'periderm', 'superficial_epidermis', 'endoderm_progenitor', 'pharyngeal_pouch', 'forerunner_cells', 'intestinal_epithelium', 'hepatocyte', 'endocrine_pancreas', 'exocrine_pancreas', 'neural_crest_progenitor', 'pharyngeal_arch_crest', 'iridophore', 'melanocyte', 'xanthophore', 'schwann', 'neural_progenitor', 'telencephalon', 'diencephalon', 'mesencephalon', 'rhombocephalon', 'spinal_cord_progenitor', 'differentiating_neurons', 'optic_cup', 'retinal_pigment_epithelium', 'retina', 'photoreceptors', 'mesoderm_progenitor', 'tailbud', 'presomitic_meso', 'adaxial', 'myotome', 'slow_muscle', 'fast_muscle', 'somites', 'dermatome', 'dermis', 'fibroblasts', 'sclerotome', 'axial_skeleton', 'tendon', 'lateral_plate_progenitor', 'pharyngeal_arch_meso', 'head_mesenchyme', 'meninges', 'periocular_meso', 'fin_bud_mesenchyme', 'fin_bud_chondrocytes', 'facial_skeleton', 'cephalic_muscle', 'visceral_smooth_muscle', 'vascular_smooth_muscle', 'cardiac_mesenchyme', 'cardiac_muscle', 'pronephros', 'vasculature', 'vein', 'endocardial', 'aorta', 'lymphatic', 'hematopoietic_progenitor', 'erythroid', 'myeloid_progenitor', 'macrophage', 'neutrophil', 'notochord', 'prechordal_plate', 'hatching_gland', 'pgc_progenitor'], time_order=None, study_order=['Kamimoto2023', 'Farrell2018', 'Kukreja2024', 'Wagner2018', 'Farnsworth2020', 'Lange2023', 'Sur2023', 'Spanjaard2018'], omit_groups=['nan', 'unknown'], edgecolor='black', edge_lw=0.1, background='white', tick_grid_x_left=False, tick_grid_x_right=False, tick_grid_y=False, tick_grid_alpha=0.15, tick_grid_lw=0.6, row_color_groups={'black': ['blastomeres'], 'blue': ['neural_progenitor', 'telencephalon', 'diencephalon', 'mesencephalon', 'rhombocephalon', 'spinal_cord_progenitor', 'differentiating_neurons'], 'crimson': ['lateral_plate_progenitor', 'pharyngeal_arch_meso', 'head_mesenchyme', 'meninges', 'periocular_meso', 'fin_bud_mesenchyme', 'fin_bud_chondrocytes', 'facial_skeleton', 'cephalic_muscle', 'visceral_smooth_muscle', 'vascular_smooth_muscle', 'cardiac_mesenchyme', 'cardiac_muscle', 'pronephros'], 'darkblue': ['optic_cup', 'retinal_pigment_epithelium', 'retina', 'photoreceptors'], 'darkorange': ['endoderm_progenitor', 'pharyngeal_pouch', 'forerunner_cells', 'intestinal_epithelium', 'hepatocyte', 'endocrine_pancreas', 'exocrine_pancreas'], 'firebrick': ['hematopoietic_progenitor', 'erythroid', 'myeloid_progenitor', 'macrophage', 'neutrophil'], 'green': ['ectoderm_progenitor', 'fin_epidermis', 'basal_epidermis', 'ionocytes', 'lens', 'lateral_line', 'olfactory', 'otic', 'periderm', 'superficial_epidermis'], 'orangered': ['vasculature', 'vein', 'endocardial', 'aorta', 'lymphatic'], 'purple': ['pgc_progenitor'], 'r': ['notochord', 'prechordal_plate', 'hatching_gland'], 'red': ['mesoderm_progenitor', 'tailbud', 'presomitic_meso', 'adaxial', 'myotome', 'slow_muscle', 'fast_muscle', 'somites', 'dermatome', 'dermis', 'fibroblasts', 'sclerotome', 'axial_skeleton', 'tendon'], 'steelblue': ['neural_crest_progenitor', 'pharyngeal_arch_crest', 'iridophore', 'melanocyte', 'xanthophore', 'schwann']}, show_row_color_legend=False, row_dividers=[1, 11, 18, 24, 31, 35, 49, 63, 68, 73, 76], row_divider_color='black', row_divider_lw=0.5, row_divider_alpha=1.0, return_long=False)

Two-panel dotplot showing a single gene (or obs feature) across cell types, split by developmental timepoint and by study.

The left panel shows (cell type × timepoint) and the right panel shows (cell type × study), both using the same color scale (mean expression) and size scale (fraction of cells expressing). This makes it easy to simultaneously assess temporal dynamics and cross-study reproducibility for any gene of interest.

color is resolved first as a gene name in adata.var_names; if no match is found it falls back to a numeric column in adata.obs.

Parameters:

• adata (anndata.AnnData) – Reference dataset. Must contain groupby, time_col, and study_col in adata.obs.

• color (str) – Gene name or numeric obs column to visualize. Gene lookup is case-sensitive and must match adata.var_names exactly.

• groupby (str) – obs column whose categories form the rows of both panels.

• time_col (str) – obs column containing developmental time group labels (e.g. "6hpf", "24hpf"). Forms the columns of the left panel.

• study_col (str) – obs column containing dataset/study identifiers. Forms the columns of the right panel.

• layer (str | None) – Layer in adata.layers to use for expression values. Falls back to adata.X when None.

• use_raw (bool | None) – If True, read expression from adata.raw. Overrides layer.

• detect_threshold (float) – Minimum value for a cell to count as “expressing” when computing the fraction-expressing dot size.

• show (bool) – Call plt.show() after rendering.

• cmap (str) – Matplotlib colormap for dot fill color (mean expression).

• vmin (float | None) – Minimum value for the color scale.

• vmax (float | None) – Maximum value for the color scale. Inferred from data when None.

• cbar_title (str) – Label for the colorbar.

• add_colorbar (bool) – Draw a colorbar for the mean expression scale.

• s_min (float) – Minimum and maximum dot sizes (in points²) for the fraction-expressing scale.

• s_max (float) – Minimum and maximum dot sizes (in points²) for the fraction-expressing scale.

• abs_min_cells (int) – Minimum absolute number of cells in a bin to render a dot. Bins with fewer cells are shown as low-support (grey).

• rel_min_frac (float) – Minimum fraction of the median bin size required to render a dot.

• low_support_grey (str) – Greyscale color for low-support / missing bins.

• cell_size (float) – Size of each data cell in both x and y dimensions, in inches. Determines the aspect ratio and overall figure size when figsize=None.

• middle_gap (float) – Gap between the left (time) and right (study) panels, in inches.

• cluster_order (list[str] | None) – Explicit ordering of rows (cell types). Defaults to the canonical ZMAP CellType order defined in the package.

• time_order (list[str] | None) – Explicit ordering of timepoint columns. Inferred from data when None.

• study_order (list[str] | None) – Explicit ordering of study columns. Defaults to the canonical ZMAP study order defined in the package.

• omit_groups (list[str] | None) – Cell-type labels to exclude from the rows.

• row_color_groups (dict[str, list[str]] | None) – {color: [group1, group2, ...]} mapping used to color row labels by lineage. Defaults to the canonical ZMAP lineage color scheme.

• row_dividers (list[int] | None) – Row indices at which to draw horizontal divider lines between lineage blocks. Defaults to the canonical ZMAP lineage boundaries.

• return_long (bool) – If True, also return the long-form pd.DataFrame used to generate the plot.

• size_zero_for_missing (bool)

• rel_abs_cap (int)

• low_support_alpha (float)

• gutter_width (float)

• gutter_pad (float)

• figsize (tuple | None)

• xlabel_rotation (int)

• title_left (str | None)

• title_right (str | None)

• show_size_legend (bool)

• size_legend_values (tuple | None)

• size_legend_title (str | None)

• size_legend_facecolor (str)

• edgecolor (str)

• edge_lw (float)

• background (str)

• tick_grid_x_left (bool)

• tick_grid_x_right (bool)

• tick_grid_y (bool)

• tick_grid_alpha (float)

• tick_grid_lw (float)

• show_row_color_legend (bool)

• row_divider_color (str)

• row_divider_lw (float)

• row_divider_alpha (float)

Returns:

The rendered figure, or (figure, long_df) when return_long=True.

Return type:

matplotlib.figure.Figure or tuple

Examples

>>> zmap.dotplot.gene_view(adata_ref, "sox2")
>>> zmap.dotplot.gene_view(adata_ref, "myod1", cmap="Reds", vmax=5)

zmap.dotplot.dotplot_gene.gene_groups_vs_time(adata, color, *, groupby='ZMAP_CellType', time_col='time_block_id', layer='tpm_log', use_raw=None, detect_threshold=0.0, show=True, cmap='viridis', vmin=0, vmax=None, standard_scale=None, s_min=4.0, s_max=60.0, size_zero_for_missing=True, abs_min_cells=10, rel_min_frac=0.01, rel_abs_cap=300, low_support_grey='0.7', low_support_alpha=0.5, base_col_width=0.14, base_row_height=0.14, gutter_width=1.5, gutter_pad=0.03, figsize=None, xlabel_rotation=90, title=None, add_colorbar=True, cbar_title='log(tpm)\\ncounts', show_size_legend=True, size_legend_values=None, size_legend_title=None, size_legend_facecolor='black', cluster_order=['blastomeres', 'ectoderm_progenitor', 'fin_epidermis', 'basal_epidermis', 'ionocytes', 'lens', 'lateral_line', 'olfactory', 'otic', 'periderm', 'superficial_epidermis', 'endoderm_progenitor', 'pharyngeal_pouch', 'forerunner_cells', 'intestinal_epithelium', 'hepatocyte', 'endocrine_pancreas', 'exocrine_pancreas', 'neural_crest_progenitor', 'pharyngeal_arch_crest', 'iridophore', 'melanocyte', 'xanthophore', 'schwann', 'neural_progenitor', 'telencephalon', 'diencephalon', 'mesencephalon', 'rhombocephalon', 'spinal_cord_progenitor', 'differentiating_neurons', 'optic_cup', 'retinal_pigment_epithelium', 'retina', 'photoreceptors', 'mesoderm_progenitor', 'tailbud', 'presomitic_meso', 'adaxial', 'myotome', 'slow_muscle', 'fast_muscle', 'somites', 'dermatome', 'dermis', 'fibroblasts', 'sclerotome', 'axial_skeleton', 'tendon', 'lateral_plate_progenitor', 'pharyngeal_arch_meso', 'head_mesenchyme', 'meninges', 'periocular_meso', 'fin_bud_mesenchyme', 'fin_bud_chondrocytes', 'facial_skeleton', 'cephalic_muscle', 'visceral_smooth_muscle', 'vascular_smooth_muscle', 'cardiac_mesenchyme', 'cardiac_muscle', 'pronephros', 'vasculature', 'vein', 'endocardial', 'aorta', 'lymphatic', 'hematopoietic_progenitor', 'erythroid', 'myeloid_progenitor', 'macrophage', 'neutrophil', 'notochord', 'prechordal_plate', 'hatching_gland', 'pgc_progenitor'], time_order=None, omit_groups=['nan', 'unknown'], edgecolor='black', edge_lw=0.1, background='white', tick_grid_x=False, tick_grid_y=False, tick_grid_alpha=0.15, tick_grid_lw=0.6, row_color_groups={'black': ['blastomeres'], 'blue': ['neural_progenitor', 'telencephalon', 'diencephalon', 'mesencephalon', 'rhombocephalon', 'spinal_cord_progenitor', 'differentiating_neurons'], 'crimson': ['lateral_plate_progenitor', 'pharyngeal_arch_meso', 'head_mesenchyme', 'meninges', 'periocular_meso', 'fin_bud_mesenchyme', 'fin_bud_chondrocytes', 'facial_skeleton', 'cephalic_muscle', 'visceral_smooth_muscle', 'vascular_smooth_muscle', 'cardiac_mesenchyme', 'cardiac_muscle', 'pronephros'], 'darkblue': ['optic_cup', 'retinal_pigment_epithelium', 'retina', 'photoreceptors'], 'darkorange': ['endoderm_progenitor', 'pharyngeal_pouch', 'forerunner_cells', 'intestinal_epithelium', 'hepatocyte', 'endocrine_pancreas', 'exocrine_pancreas'], 'firebrick': ['hematopoietic_progenitor', 'erythroid', 'myeloid_progenitor', 'macrophage', 'neutrophil'], 'green': ['ectoderm_progenitor', 'fin_epidermis', 'basal_epidermis', 'ionocytes', 'lens', 'lateral_line', 'olfactory', 'otic', 'periderm', 'superficial_epidermis'], 'orangered': ['vasculature', 'vein', 'endocardial', 'aorta', 'lymphatic'], 'purple': ['pgc_progenitor'], 'r': ['notochord', 'prechordal_plate', 'hatching_gland'], 'red': ['mesoderm_progenitor', 'tailbud', 'presomitic_meso', 'adaxial', 'myotome', 'slow_muscle', 'fast_muscle', 'somites', 'dermatome', 'dermis', 'fibroblasts', 'sclerotome', 'axial_skeleton', 'tendon'], 'steelblue': ['neural_crest_progenitor', 'pharyngeal_arch_crest', 'iridophore', 'melanocyte', 'xanthophore', 'schwann']}, show_row_color_legend=False, row_dividers=[1, 11, 18, 24, 31, 35, 49, 63, 68, 73, 76], row_divider_color='black', row_divider_lw=0.5, row_divider_alpha=1, return_long=False)

Dotplot of a single gene across cell types and developmental timepoints.

Renders a (cell type × timepoint) grid where dot color encodes mean expression and dot size encodes the fraction of cells expressing the gene above detect_threshold. Bins with insufficient cells are shown as grey dots at minimum size.

color is resolved first as a gene name in adata.var_names (or adata.raw / adata.layers[layer]); if no match is found it falls back to a numeric column in adata.obs.

Parameters:

• adata (anndata.AnnData) – Reference dataset containing expression data and obs columns for groupby and time_col.

• color (str) – Gene name or numeric obs column to visualize.

• groupby (str) – obs column whose categories form the rows.

• time_col (str) – obs column containing developmental time group labels (columns).

• layer (str | None) – Layer to use for expression values.

• use_raw (bool | None) – If True, use adata.raw.

• detect_threshold (float) – Minimum value for a cell to count as “expressing”.

• show (bool) – Call plt.show() after rendering.

• cmap (str) – Colormap for mean expression.

• vmin (float | None) – Color scale limits.

• vmax (float | None) – Color scale limits.

• standard_scale (str | None) – Scale values per timepoint ("time") or per cluster ("cluster").

• s_min (float) – Dot size range in points squared.

• s_max (float) – Dot size range in points squared.

• cluster_order (list[str] | None) – Explicit row ordering. Defaults to the canonical ZMAP CellType order.

• time_order (list[str] | None) – Explicit column ordering. Inferred from data when None.

• omit_groups (list[str] | None) – Cell-type labels to exclude.

• row_color_groups (dict[str, list[str]] | None) – {color: [group, ...]} mapping to color row labels by lineage.

• row_dividers (list[int] | None) – Row indices at which to draw horizontal divider lines.

• return_long (bool) – Also return the underlying long-form DataFrame.

• size_zero_for_missing (bool)

• abs_min_cells (int)

• rel_min_frac (float)

• rel_abs_cap (int)

• low_support_grey (str)

• low_support_alpha (float)

• base_col_width (float)

• base_row_height (float)

• gutter_width (float)

• gutter_pad (float)

• figsize (tuple | None)

• xlabel_rotation (int)

• title (str | None)

• add_colorbar (bool)

• cbar_title (str)

• show_size_legend (bool)

• size_legend_values (tuple | None)

• size_legend_title (str | None)

• size_legend_facecolor (str)

• edgecolor (str)

• edge_lw (float)

• background (str)

• tick_grid_x (bool)

• tick_grid_y (bool)

• tick_grid_alpha (float)

• tick_grid_lw (float)

• show_row_color_legend (bool)

• row_divider_color (str)

• row_divider_lw (float)

• row_divider_alpha (float)

Returns:

(ax, long_df) where long_df is the aggregated data table when return_long=True, otherwise None.

Return type:

tuple of (matplotlib.axes.Axes, pd.DataFrame or None)

Examples

>>> ax, _ = zmap.dotplot.dotplot_gene.gene_groups_vs_time(adata_ref, "sox2")

zmap.dotplot.dotplot_gene.gene_groups_vs_studies(adata, color, *, groupby='ZMAP_CellType', study_col='study_id', layer='tpm_log', use_raw=None, detect_threshold=0.0, show=True, cmap='viridis', vmin=0, vmax=None, standard_scale=None, s_min=4.0, s_max=60.0, size_zero_for_missing=True, abs_min_cells=10, rel_min_frac=0.01, rel_abs_cap=300, low_support_grey='0.7', low_support_alpha=0.5, base_col_width=0.14, base_row_height=0.14, gutter_width=1.5, gutter_pad=0.03, figsize=None, xlabel_rotation=90, title=None, add_colorbar=True, cbar_title='log(tpm)\\ncounts', show_size_legend=True, size_legend_values=None, size_legend_title=None, size_legend_facecolor='black', cluster_order=['blastomeres', 'ectoderm_progenitor', 'fin_epidermis', 'basal_epidermis', 'ionocytes', 'lens', 'lateral_line', 'olfactory', 'otic', 'periderm', 'superficial_epidermis', 'endoderm_progenitor', 'pharyngeal_pouch', 'forerunner_cells', 'intestinal_epithelium', 'hepatocyte', 'endocrine_pancreas', 'exocrine_pancreas', 'neural_crest_progenitor', 'pharyngeal_arch_crest', 'iridophore', 'melanocyte', 'xanthophore', 'schwann', 'neural_progenitor', 'telencephalon', 'diencephalon', 'mesencephalon', 'rhombocephalon', 'spinal_cord_progenitor', 'differentiating_neurons', 'optic_cup', 'retinal_pigment_epithelium', 'retina', 'photoreceptors', 'mesoderm_progenitor', 'tailbud', 'presomitic_meso', 'adaxial', 'myotome', 'slow_muscle', 'fast_muscle', 'somites', 'dermatome', 'dermis', 'fibroblasts', 'sclerotome', 'axial_skeleton', 'tendon', 'lateral_plate_progenitor', 'pharyngeal_arch_meso', 'head_mesenchyme', 'meninges', 'periocular_meso', 'fin_bud_mesenchyme', 'fin_bud_chondrocytes', 'facial_skeleton', 'cephalic_muscle', 'visceral_smooth_muscle', 'vascular_smooth_muscle', 'cardiac_mesenchyme', 'cardiac_muscle', 'pronephros', 'vasculature', 'vein', 'endocardial', 'aorta', 'lymphatic', 'hematopoietic_progenitor', 'erythroid', 'myeloid_progenitor', 'macrophage', 'neutrophil', 'notochord', 'prechordal_plate', 'hatching_gland', 'pgc_progenitor'], study_order=['Kamimoto2023', 'Farrell2018', 'Kukreja2024', 'Wagner2018', 'Farnsworth2020', 'Lange2023', 'Sur2023', 'Spanjaard2018'], omit_groups=['nan', 'unknown'], edgecolor='black', edge_lw=0.1, background='white', tick_grid_x=False, tick_grid_y=False, tick_grid_alpha=0.15, tick_grid_lw=0.6, row_color_groups={'black': ['blastomeres'], 'blue': ['neural_progenitor', 'telencephalon', 'diencephalon', 'mesencephalon', 'rhombocephalon', 'spinal_cord_progenitor', 'differentiating_neurons'], 'crimson': ['lateral_plate_progenitor', 'pharyngeal_arch_meso', 'head_mesenchyme', 'meninges', 'periocular_meso', 'fin_bud_mesenchyme', 'fin_bud_chondrocytes', 'facial_skeleton', 'cephalic_muscle', 'visceral_smooth_muscle', 'vascular_smooth_muscle', 'cardiac_mesenchyme', 'cardiac_muscle', 'pronephros'], 'darkblue': ['optic_cup', 'retinal_pigment_epithelium', 'retina', 'photoreceptors'], 'darkorange': ['endoderm_progenitor', 'pharyngeal_pouch', 'forerunner_cells', 'intestinal_epithelium', 'hepatocyte', 'endocrine_pancreas', 'exocrine_pancreas'], 'firebrick': ['hematopoietic_progenitor', 'erythroid', 'myeloid_progenitor', 'macrophage', 'neutrophil'], 'green': ['ectoderm_progenitor', 'fin_epidermis', 'basal_epidermis', 'ionocytes', 'lens', 'lateral_line', 'olfactory', 'otic', 'periderm', 'superficial_epidermis'], 'orangered': ['vasculature', 'vein', 'endocardial', 'aorta', 'lymphatic'], 'purple': ['pgc_progenitor'], 'r': ['notochord', 'prechordal_plate', 'hatching_gland'], 'red': ['mesoderm_progenitor', 'tailbud', 'presomitic_meso', 'adaxial', 'myotome', 'slow_muscle', 'fast_muscle', 'somites', 'dermatome', 'dermis', 'fibroblasts', 'sclerotome', 'axial_skeleton', 'tendon'], 'steelblue': ['neural_crest_progenitor', 'pharyngeal_arch_crest', 'iridophore', 'melanocyte', 'xanthophore', 'schwann']}, show_row_color_legend=False, row_dividers=[1, 11, 18, 24, 31, 35, 49, 63, 68, 73, 76], row_divider_color='black', row_divider_lw=0.5, row_divider_alpha=1, return_long=False)

Dotplot of a single gene across cell types and studies.

Renders a (cell type × study) grid where dot color encodes mean expression and dot size encodes the fraction of cells expressing the gene above detect_threshold. Useful for assessing cross-study reproducibility of marker gene expression patterns.

color is resolved first as a gene name in adata.var_names; if no match is found it falls back to a numeric column in adata.obs.

Parameters:

• adata (anndata.AnnData) – Reference dataset containing expression data and obs columns for groupby and study_col.

• color (str) – Gene name or numeric obs column to visualize.

• groupby (str) – obs column whose categories form the rows.

• study_col (str) – obs column containing study identifiers (columns).

• layer (str | None) – Layer to use for expression values.

• use_raw (bool | None) – If True, use adata.raw.

• detect_threshold (float) – Minimum value for a cell to count as “expressing”.

• show (bool) – Call plt.show() after rendering.

• cmap (str) – Colormap for mean expression.

• vmin (float | None) – Color scale limits.

• vmax (float | None) – Color scale limits.

• standard_scale (str | None) – Scale values per study ("study") or per cluster ("cluster").

• s_min (float) – Dot size range in points squared.

• s_max (float) – Dot size range in points squared.

• cluster_order (list[str] | None) – Explicit row ordering. Defaults to the canonical ZMAP CellType order.

• study_order (list[str] | None) – Explicit column ordering. Defaults to the canonical ZMAP study order.

• omit_groups (list[str] | None) – Cell-type labels to exclude.

• row_color_groups (dict[str, list[str]] | None) – {color: [group, ...]} mapping to color row labels by lineage.

• row_dividers (list[int] | None) – Row indices at which to draw horizontal divider lines.

• return_long (bool) – Also return the underlying long-form DataFrame.

• size_zero_for_missing (bool)

• abs_min_cells (int)

• rel_min_frac (float)

• rel_abs_cap (int)

• low_support_grey (str)

• low_support_alpha (float)

• base_col_width (float)

• base_row_height (float)

• gutter_width (float)

• gutter_pad (float)

• figsize (tuple | None)

• xlabel_rotation (int)

• title (str | None)

• add_colorbar (bool)

• cbar_title (str)

• show_size_legend (bool)

• size_legend_values (tuple | None)

• size_legend_title (str | None)

• size_legend_facecolor (str)

• edgecolor (str)

• edge_lw (float)

• background (str)

• tick_grid_x (bool)

• tick_grid_y (bool)

• tick_grid_alpha (float)

• tick_grid_lw (float)

• show_row_color_legend (bool)

• row_divider_color (str)

• row_divider_lw (float)

• row_divider_alpha (float)

Returns:

(ax, long_df) where long_df is the aggregated data table when return_long=True, otherwise None.

Return type:

tuple of (matplotlib.axes.Axes, pd.DataFrame or None)

Examples

>>> ax, _ = zmap.dotplot.dotplot_gene.gene_groups_vs_studies(adata_ref, "myod1")

Group-Centric Dotplots

zmap.dotplot.group_siblings_vs_markers(adata, node, *, level_col=None, parent_col=None, marker_type='overall', n_markers=20, min_support_ratio=None, min_log2fc=None, min_enrich=None, omit_unannotated=True, layer='tpm_log', use_raw=None, highlight_color='black', standard_scale=None, cmap='Blues', enforce_global_colorscale=False, width_per_gene=0.04, height_per_group=0.2, min_figsize=(0.5, 0.5), max_figsize=(25.0, 25.0), hspace=0.04, left_time_strip=False, consensus_panel=None, show_size_legend=True, xlabel_rotation=90, duplicate_gene_columns=False, show_ring_legend=True, add_colorbar=True, sibling_title=None, tissue_title=None, **dotplot_kwargs)

Two-block dotplot comparing a focal cell type to its siblings and tissues.

Given a focal node (e.g. "hepatocyte"), this function:

• Fetches the consensus marker genes for that node.

• Plots a sibling block (top): all cell types sharing the same parent in the ZMAP hierarchy, colored by mean expression of the focal node’s markers.

• Plots a tissue block (bottom): all ZMAP_Tissue groups, showing how broadly those same marker genes are expressed across tissues.

Both blocks share the same gene columns, color scale, and right-hand legend. Row order in both blocks is by descending mean expression across the marker genes. Rings in the tissue block encode support_ratio from the Tissue-level consensus marker table, indicating cross-study reproducibility.

Parameters:

• adata (AnnData) – Reference dataset. Must contain the relevant obs columns for the ZMAP hierarchy (e.g. ZMAP_CellType, ZMAP_Tissue).

• node (str) – The focal cell type or cluster whose markers and siblings to plot (e.g. "hepatocyte", "Neurons").

• level_col (str | None) – obs column defining the annotation level of node (e.g. "ZMAP_CellType"). Auto-detected from the data when None.

• parent_col (str | None) – obs column defining the parent level used to identify siblings (e.g. "ZMAP_Tissue"). Inferred from level_col when None.

• marker_type (Literal['overall', 'exclusivity', 'contrast', 'consensus']) – Scoring criterion for selecting markers. One of "overall", "exclusivity", "contrast", "consensus".

• n_markers (int) – Number of top marker genes to display as columns.

• min_support_ratio (float | None) – Optional filters applied to the marker table before selecting genes. See load_consensus_markers for definitions.

• min_log2fc (float | None) – Optional filters applied to the marker table before selecting genes. See load_consensus_markers for definitions.

• min_enrich (float | None) – Optional filters applied to the marker table before selecting genes. See load_consensus_markers for definitions.

• omit_unannotated (bool) – Remove genes with unannotated/placeholder names from the marker set.

• layer (str | None) – Layer in adata.layers to use for expression values. Falls back to adata.X when None.

• use_raw (bool | None) – If True, use adata.raw for expression. Overrides layer.

• highlight_color (str) – Color used to highlight the focal node’s row in the sibling block.

• standard_scale (Optional[Literal['var', 'obs']]) – Scale expression values per gene ("var") or per cell ("obs") before computing dot statistics. None applies no scaling.

• cmap (str) – Matplotlib colormap for dot fill color.

• enforce_global_colorscale (bool) – If True, use a single shared color scale across both blocks. If False, each block is scaled independently.

• width_per_gene (float) – Figure width contribution per gene column, in inches.

• height_per_group (float) – Figure height contribution per row (group), in inches.

• min_figsize (tuple[float, float]) – Hard lower and upper bounds on the auto-computed figure size.

• max_figsize (tuple[float, float]) – Hard lower and upper bounds on the auto-computed figure size.

• hspace (float) – Vertical gap between the sibling and tissue blocks.

• left_time_strip (bool) – Draw a developmental time distribution strip on the left margin.

• consensus_panel (str | None) – If provided, add an additional panel showing support ratios from the specified consensus level (e.g. "Tissue").

• show_size_legend (bool) – Show the dot-size legend (fraction of cells expressing each gene).

• xlabel_rotation (int) – Rotation angle for gene name tick labels on the x-axis.

• duplicate_gene_columns (bool) – Repeat the gene column labels on both the top and bottom axes.

• show_ring_legend (bool) – Show the ring (support_ratio) legend in the tissue block.

• add_colorbar (bool) – Add a colorbar for mean expression.

• sibling_title (str | None) – Custom titles for the sibling and tissue blocks respectively. Auto-generated when None.

• tissue_title (str | None) – Custom titles for the sibling and tissue blocks respectively. Auto-generated when None.

• **dotplot_kwargs – Additional keyword arguments forwarded to the underlying dotplot rendering functions.

Returns:

The rendered figure.

Return type:

matplotlib.figure.Figure

Examples

>>> zmap.dotplot.group_siblings_vs_markers(adata_ref, "hepatocyte")
>>> zmap.dotplot.group_siblings_vs_markers(adata_ref, "Neurons", n_markers=15, cmap="Reds")

zmap.dotplot.group_descendants_vs_markers(adata, parent=None, *, parent_col=None, child_col=None, celltype=None, celltype_col=None, cluster_col=None, layer='tpm_log', use_raw=None, marker_type='overall', n_markers_per_group=5, min_support_ratio=None, min_log2fc=None, min_enrich=None, omit_unannotated=True, min_cells_per_group=None, use_dendrogram_rows=True, dendrogram_metric='correlation', dendrogram_method='average', standard_scale='var', detect_threshold=0.0, cmap='Blues', consensus_panel=None, stacked_bar_show_legend=True, group_color_dict=None, duplicate_gene_columns=False, figsize=None, min_figsize=(10.0, 6.0), max_figsize=(80.0, 40.0), width_per_gene=0.15, height_per_group=0.15, left_margin=1.5, right_margin=2.5, top_margin=1.0, bottom_margin=1.0, s_min=1.0, s_max=80.0, xlabel_rotation=90, title=None, show_size_legend=True, **dotplot_kwargs)

Dotplot showing the child groups within a parent group, colored by their marker genes.

Given a parent label (e.g. "forebrain" at the Tissue level), plots all child groups at the next level down (e.g. Clusters or Leiden clusters) as rows, with each child group’s consensus marker genes as columns. Gene columns are ordered by child group, and rows are optionally ordered by a dendrogram computed over mean expression profiles.

Typical usage:

• parent_col="ZMAP_Tissue", child_col="ZMAP_Cluster", parent="forebrain"

• parent_col="ZMAP_CellType", child_col="leiden_100", parent="Neurons"

Parameters:

• adata (AnnData) – Reference dataset. Must contain both parent_col and child_col in adata.obs.

• parent (Optional[str]) – The specific parent label to drill into (e.g. "forebrain"). Required — raises ValueError when None.

• parent_col (str) – obs column at the parent level (e.g. "ZMAP_Tissue"). Auto-detected via the ZMAP hierarchy when None.

• child_col (str) – obs column at the child level to use as rows (e.g. "ZMAP_Cluster", "leiden_100"). Required.

• layer (Optional[str]) – Layer in adata.layers to use for expression values. Falls back to adata.X when None.

• use_raw (Optional[bool]) – If True, use adata.raw for expression. Overrides layer.

• marker_type (Literal['specificity', 'contrast', 'consensus', 'overall']) – Scoring criterion for selecting markers per child group. One of "specificity", "contrast", "consensus", "overall".

• n_markers_per_group (Optional[int]) – Number of top marker genes to display per child group as columns.

• min_support_ratio (Optional[float]) – Optional filters applied to the marker table. See load_consensus_markers.

• min_log2fc (Optional[float]) – Optional filters applied to the marker table. See load_consensus_markers.

• min_enrich (Optional[float]) – Optional filters applied to the marker table. See load_consensus_markers.

• omit_unannotated (bool) – Remove genes with unannotated/placeholder names from the marker set.

• min_cells_per_group (Optional[int]) – Exclude child groups with fewer than this many cells.

• use_dendrogram_rows (bool) – Reorder rows by a hierarchical clustering dendrogram computed over mean expression profiles.

• dendrogram_metric (str) – Distance metric for the row dendrogram.

• dendrogram_method (str) – Linkage method for the row dendrogram.

• standard_scale (Optional[str]) – Scale expression per gene ("var") or per cell ("obs"). None applies no scaling.

• detect_threshold (float) – Minimum expression value for a cell to count as “expressing” a gene when computing the fraction-expressing dot size.

• cmap (str) – Matplotlib colormap for dot fill color.

• consensus_panel (Optional[str]) – Add a panel showing support ratios from the specified consensus level.

• group_color_dict (Optional[Mapping[str, str]]) – {group_label: color} mapping for child group row labels.

• duplicate_gene_columns (bool) – Repeat gene column labels on both top and bottom of the figure.

• figsize (Optional[Tuple[float, float]]) – Explicit figure size (width, height) in inches. Auto-computed when None.

• min_figsize (Tuple[float, float]) – Hard bounds on the auto-computed figure size.

• max_figsize (Tuple[float, float]) – Hard bounds on the auto-computed figure size.

• width_per_gene (float) – Per-gene and per-row size contributions when auto-computing figure size.

• height_per_group (float) – Per-gene and per-row size contributions when auto-computing figure size.

• s_min (float) – Minimum and maximum dot sizes (in points²) for the fraction-expressing scale.

• s_max (float) – Minimum and maximum dot sizes (in points²) for the fraction-expressing scale.

• xlabel_rotation (int) – Rotation angle for gene name tick labels.

• title (Optional[str]) – Figure title. Auto-generated when None.

• show_size_legend (bool) – Show the dot-size legend.

• **dotplot_kwargs – Additional keyword arguments forwarded to the underlying dotplot renderer.

• celltype (str | None)

• celltype_col (str | None)

• cluster_col (str | None)

• stacked_bar_show_legend (bool)

• left_margin (float)

• right_margin (float)

• top_margin (float)

• bottom_margin (float)

Returns:

The rendered figure.

Return type:

matplotlib.figure.Figure

Notes

The celltype, celltype_col, and cluster_col parameter names are deprecated aliases for parent, parent_col, and child_col respectively, and will be removed in a future release.

Examples

>>> zmap.dotplot.group_descendants_vs_markers(
...     adata_ref,
...     parent="forebrain",
...     parent_col="ZMAP_Tissue",
...     child_col="ZMAP_Cluster",
... )

Low-Level Engine

zmap.dotplot.dotplot_group.plot_dotplot_basegrid(adata, design_df, *, groupby='ZMAP_CellType', layer=None, use_raw=None, detect_threshold=0.0, support_col='support_ratio', add_support_ring=True, ring_min_lw=0.02, ring_max_lw=1.5, ring_color='darkorange', ring_alpha=0.8, cmap='Blues', vmin=None, vmax=None, standard_scale=None, size_mode='sqrt', s_min=1, s_max=80, rowlabel_append_child_counts=True, rowlabel_child_col='ZMAP_Cluster', rowlabel_fmt='{name} ({n})', figsize=(12, 12), xlabel_rotation=90, title=None, add_colorbar=True, cbar_title='log(tpm)\\ncounts', cbar_title_fontsize=8.0, cbar_ticklabel_fontsize=8.0, xticklabel_fontsize=10.0, yticklabel_fontsize=10.0, show_size_legend=True, size_legend_fracs=(1.0, 0.75, 0.5, 0.25, 0.1), size_legend_title='Fraction\\nExpressing', size_legend_loc='upper left', size_legend_bbox_to_anchor=(0.0, 0.7), size_legend_label_fmt='{:.0%}', size_legend_facecolor='black', size_legend_edgecolor='black', size_legend_edge_lw=0.1, size_legend_framealpha=0.9, size_legend_title_fontsize=8.0, size_legend_label_fontsize=8.0, show_ring_legend=True, ring_legend_fracs=(1, 0.5, 0.1), ring_legend_title='Consensus\\nsupport', ring_legend_loc='lower left', ring_legend_bbox_to_anchor=(0.0, 0.25), ring_legend_label_fmt='{:.0%}', ring_legend_title_fontsize=8.0, ring_legend_label_fontsize=8.0, consensus_panel=None, support_stack_field='supporting_study_names', support_line_agg='median', support_line_color='black', support_line_lw=1, support_line_marker='', support_line_ms=0, support_line_alpha=0.9, support_line_ylim=(0.0, 1.2), support_grid_show_legend=False, support_grid_legend_ncols=2, stacked_bar_show_legend=True, stacked_bar_legend_ncols=2, support_strip_agg='median', support_strip_cmap='grey', support_strip_vmin=0.0, support_strip_vmax=1.0, support_strip_show_colorbar=False, support_palette_from_cmap=None, support_palette_range=(0.1, 0.9), group_color_dict=None, duplicate_gene_columns=True, draw_group_separators=True, separator_color='0.88', separator_lw=0.7, separator_ls='-', include_outer_separators=False, left_time_strip=False, time_key='time_id', time_cmap='jet', time_vmin=0.0, time_vmax=120.0, yticklabel_gap_pt=18.0, time_strip_show_yticklabels=False, time_strip_label_colors=None, consensus_height_in=0.35, support_grid_height_in=None, stacked_bar_height_in=None, strip_height_pt=12.0, time_strip_width_pt=12.0, time_strip_gap_pt=4.0, cbar_width_pt=12.0, cbar_height_frac=0.9, cbar_bbox_to_anchor=(1.05, 0.85), right_gutter_frac=0.82, ax=None, ax_leg=None, adjust_right_gutter=True)

Low-level rendering engine for ZMAP dotplots.

Takes a design DataFrame specifying which (cell type, gene) pairs to plot, computes mean expression and fraction-expressing statistics from adata, and renders the result as a scatter-based dotplot with optional support rings, consensus panels, time strips, colorbars, and size legends.

This function is the shared backend for group_siblings_vs_markers() and group_descendants_vs_markers(). Most users should call one of those higher-level wrappers instead of invoking this directly.

Parameters:

• adata (anndata.AnnData) – Reference dataset containing expression data and obs annotations.

• design_df (pd.DataFrame) – Long-form table with at least columns ["celltype", "gene"]. Each row defines one dot in the grid. An optional support_ratio column adds consensus-support rings.

• groupby (str) – obs column whose categories form the rows of the dotplot.

• layer (str | None) – Layer to use for expression values. Falls back to adata.X.

• use_raw (bool | None) – If True, use adata.raw for expression. Overrides layer.

• detect_threshold (float) – Minimum value for a cell to count as “expressing”.

• cmap (str) – Matplotlib colormap for dot fill color (mean expression).

• vmin (float | None) – Colormap normalization limits. Inferred from data when None.

• vmax (float | None) – Colormap normalization limits. Inferred from data when None.

• standard_scale (str | None) – Scale mean expression per gene ("var") or per group ("obs").

• s_min (float) – Minimum and maximum dot sizes (points squared).

• s_max (float) – Minimum and maximum dot sizes (points squared).

• add_support_ring (bool) – Draw orange rings whose thickness encodes support_ratio.

• consensus_panel (str | None) – Type of consensus summary panel above the dotplot. One of None, "line", "support_grid", "stacked_bar", "strip".

• left_time_strip (bool) – Draw a vertical developmental-time strip to the left of the dotplot.

• ax (plt.Axes | None) – Pre-existing axes to draw into. A new figure is created when None.

• support_col (str)

• ring_min_lw (float)

• ring_max_lw (float)

• ring_color (str)

• ring_alpha (float)

• size_mode (str)

• rowlabel_append_child_counts (bool)

• rowlabel_child_col (str)

• rowlabel_fmt (str)

• xlabel_rotation (int)

• title (str | None)

• add_colorbar (bool)

• cbar_title (str)

• cbar_title_fontsize (float)

• cbar_ticklabel_fontsize (float)

• xticklabel_fontsize (float)

• yticklabel_fontsize (float)

• show_size_legend (bool)

• size_legend_fracs (tuple)

• size_legend_title (str)

• size_legend_loc (str)

• size_legend_bbox_to_anchor (tuple | None)

• size_legend_label_fmt (str)

• size_legend_facecolor (str)

• size_legend_edgecolor (str)

• size_legend_edge_lw (float)

• size_legend_framealpha (float)

• size_legend_title_fontsize (float)

• size_legend_label_fontsize (float)

• show_ring_legend (bool)

• ring_legend_fracs (tuple)

• ring_legend_title (str)

• ring_legend_loc (str)

• ring_legend_bbox_to_anchor (tuple | None)

• ring_legend_label_fmt (str)

• ring_legend_title_fontsize (float)

• ring_legend_label_fontsize (float)

• support_stack_field (str)

• support_line_agg (str)

• support_line_color (str)

• support_line_lw (float)

• support_line_marker (str)

• support_line_ms (float)

• support_line_alpha (float)

• support_line_ylim (tuple | None)

• support_grid_show_legend (bool)

• support_grid_legend_ncols (int)

• stacked_bar_show_legend (bool)

• stacked_bar_legend_ncols (int)

• support_strip_agg (str)

• support_strip_cmap (str)

• support_strip_vmin (float | None)

• support_strip_vmax (float | None)

• support_strip_show_colorbar (bool)

• support_palette_from_cmap (str | mpl.colors.Colormap | None)

• support_palette_range (tuple[float, float])

• group_color_dict (dict[str, str] | None)

• duplicate_gene_columns (bool)

• draw_group_separators (bool)

• separator_color (str)

• separator_lw (float)

• separator_ls (str)

• include_outer_separators (bool)

• time_key (str)

• time_cmap (str)

• time_vmin (float)

• time_vmax (float)

• yticklabel_gap_pt (float)

• time_strip_show_yticklabels (bool)

• time_strip_label_colors (dict[str, str] | None)

• consensus_height_in (float)

• support_grid_height_in (float | None)

• stacked_bar_height_in (float | None)

• strip_height_pt (float)

• time_strip_width_pt (float)

• time_strip_gap_pt (float)

• cbar_width_pt (float)

• cbar_height_frac (float)

• cbar_bbox_to_anchor (tuple | None)

• right_gutter_frac (float)

• ax_leg (plt.Axes | None)

• adjust_right_gutter (bool)

Returns:

(ax, grid) where ax is the dotplot axes and grid is the long-form DataFrame used for rendering, with computed columns mean_expr, frac_pos, and positional indices.

Return type:

tuple of (matplotlib.axes.Axes, pd.DataFrame)