Plotting API reference

cytearc.plotting is CyteArc’s plotting API. Import it as splt and call functions such as splt.embedding(...), splt.dotplot(...), and splt.cluster_tree(...). For functions whose first argument is a datastore, ds.plots.embedding(...) and related accessor methods provide the same behavior with that argument already bound. Store-backed graph plotters mirror their DataStore counterparts and require an exact graph= reference. dotplot and matrixplot take features= as gene names or FeatureRef values, or as a mapping of group names to such lists. Diagnostics remain standalone: qc takes a DataFrame, elbow and highly_variable_features take arrays, and graph_qc takes a sparse graph.

A completed PipelineRun can be passed to ds.plots.embedding(run=run, layout="umap", color_by="clusters"). The run supplies the layout (layout names a run output, "umap" by default) and the cells, and every cell input comes from the run. There is no live fallback in run mode:

• color_by takes one item or a list, drawn as one panel each. A string or CellField names a frozen run cell field from run.cells.columns, such as clusters, doublet_score, or a column frozen with snapshot_columns. An ArtifactRef must be an output of the run, such as run["leiden_1.0"]. Any other ref raises ValueError; color by it with the granular layout=run["umap"] route instead.

• facet_by, subset_by, Highlight(by=...) and DensityOverlay(group_by=...) name frozen run cell fields. A name that is neither a frozen field nor, for color_by, a gene raises KeyError listing the run’s cell fields.

• A gene name or FeatureRef reads the live counts of the run’s assay over the run’s cells and normalizes them with the assay’s live normalizer. A run freezes no gene values, so a gene color requires an explicit normalization=NormalizationSpec(...), which provenance records; without one it raises ValueError.

• cell_key other than "I", a from_assay other than the run’s assay, and point_sizes raise ValueError. For per-cell sizes, pass layout=run["umap"] with sizes in that layout’s cell order.

Run plots record the run as provenance.extras["run"], a mapping with runId and label. layout_key= remains the live-metadata source. Mixed source modes are rejected. For large continuous fields, ds.plots.embedding_raster(run=run, layout="umap", color_by="doublet_score") uses the same frozen run selection blockwise; its color_by (a string or CellField) and subset_by name frozen run cell fields.

Granular workflows pass exact refs to the same datastore-owned plotting surface:

Plot	Explicit artifact inputs
embedding	layout=embedding_ref, optionally color_by=cluster_ref
dot or matrix plot	groups=cluster_ref
composition	categories=cluster_ref
distribution	grouping=cluster_ref
cluster connectivity	graph=graph_ref, groups=cluster_ref, layout=embedding_ref
modality weights	graph=wnn_graph_ref, layout=embedding_ref
Paris hierarchy	graph=graph_ref, clusters=paris_ref
marker heatmap	marker=marker_ref
pseudotime heatmap	aggregation=aggregation_ref
mapping score	mapping_score(result_ref, reference=reference, layout=embedding_ref)
label-transfer evidence, confusion, and calibration	mapping_evidence(transfer_ref), mapping_confusion(transfer_ref, known_labels=...), mapping_calibration(transfer_ref, known_labels=...)

layout_key and string forms on plotters that still accept them refer to deliberate live metadata inputs. Distribution grouping instead requires either an exact categorical artifact or an explicit CellField, with cell_selection= when a frozen metadata subset is intended.

Dot plots and matrix plots name the grouping columns of their tables by role, whatever the grouping columns are called: group holds the first group_by key’s values or the groups= labels, subgroup the second key’s values, and sample the sample_by value. They are followed by feature, feature_group, mean, fraction, n_cells and variance, and an aggregate over samples adds n_samples. A grouping column can therefore be named feature, mean or sample, and provenance.extras["group_by"] keeps the source column names. With standardize="feature", mean stays raw and a zscore column of tables["aggregate"] holds the plotted values, while tables["per_sample"] keeps the per-sample means without it; provenance.extras["color_values"] names the plotted column. A matrix plot’s tables["matrix"] is the drawn matrix, like the matrix of marker_heatmap: one row per feature (index feature) and one column per group label (columns group). marker_heatmap’s matrix holds the standardized values of its marker features, one column per group of the marker search. The annotation tables of both are indexed by the same labels.

Plots treat rows that a nullable metadata column or label artifact flags in its linked missing mask as missing, never as their stored placeholder. Dot plots and matrix plots leave those cells out of every group and report their number as dropped_group_cells. Composition plots count a missing category in the NA category and leave cells with a missing sample label out of every sample. Embeddings and cluster trees show missing colors or fill values as missing, and cluster_connectivity rejects missing group labels and coordinates.

A feature has no value in a cell that its assay did not measure, which the assay’s membership column <assay>_I marks False (Assay membership); such a cell holds zero counts, which are no measurement. Plots read only the measured cells and normalize only them, so a normalizer fitted over the cells that it reads, such as ATAC TF-IDF, gives a measured cell the value of a read of the measured cells alone. Embeddings draw an unmeasured cell in the scale’s missing_color and leave it out of the color limits, and provenance.extras["color_limits"] holds None for a color or panel without a value among the drawn cells. Distribution plots leave it out of the feature’s panel and table, and a feature panel whose assay measured none of the selected cells raises ValueError that names the membership column. Dot plots and matrix plots compute mean, fraction, and variance over the cells of a group with a value, which n_cells counts, so fraction is the share of measured cells above expression_cutoff; a group without a measured cell keeps its row with n_cells 0 and NaN statistics and draws no dot or a missing matrix cell, and an aggregate over samples skips such a sample in every statistic and in n_samples. Cluster-tree fill values and the group means of marker_heatmap leave out unmeasured cells. Dot plots, matrix plots, embeddings, distribution plots, and marker_heatmap record provenance.extras["unmeasured_cells"], a mapping from each feature assay to the number of plotted cells that it did not measure, when that number is not zero.

WNN is the default for DataStore.integration.modalities. Its integrated graph stores one weight per input assay and cell. Use ds.plots.modality_weights(graph=wnn_graph, layout=embedding) or cytearc.plotting.modality_weights() to show those weights over an explicit embedding. The graph and layout must have the exact same cell-selection artifact. Explicit SNN graphs do not contain modality weights.

Store-backed plotters and diagnostics generally return a PlotResult and render by default with show=True. Pass show=False before accessing, saving, or reusing an owned figure. run_recipe returns a PlotRecipeResult and defaults to show=False. Helpers differ: label_panels returns None, theme_context is an iterator, and compose_results returns a PlotResult without a show parameter.

cytearc.plotting.cluster_connectivity(store, *, group_by=None, layout_key=None, groups=None, layout=None, graph, cell_key='I', position='median', positions=None, categorical_scale=None, size_scale=None, minimum_edge_weight=0.02, max_edges_per_node=None, show_cells=False, cell_size=None, cell_alpha=0.3, cell_color=None, node_edgecolor=None, node_linewidth=0.8, edge_color=None, edge_alpha=0.45, edge_width_range=(0.4, 5.0), labels=True, target=None, figsize=None, theme='notebook', show=True)

Plot cluster connectivity on an existing two-dimensional cell layout.

rawWeight is the sum of intercluster weights after reciprocal sparse graph entries are counted once. normalizedWeight divides that value by sqrt(incidentWeight[source] * incidentWeight[target]). Incident weight is the sum of weighted cell degrees in each cluster, including internal cluster edges. Clusters with zero incident weight receive a normalized value of zero.

Return type:

PlotResult

cytearc.plotting.cluster_tree(store, *, graph, clusters, from_assay=None, fill_by_value=None, force_ints_as_cats=True, width=1, lvr_factor=0.5, vert_gap=0.2, min_node_size=10, node_size_multiplier=10000.0, node_power=1.2, root_size=100, non_leaf_size=10, show_labels=True, fontsize=10, root_color='#C0C0C0', non_leaf_color='k', cmap='tab20', color_key=None, edgecolors='k', edgewidth=1, alpha=0.7, figsize=(5, 5), ax=None, theme='notebook', show=True)

Plot the coalesced hierarchy for a clustering result.

Return type:

PlotResult

cytearc.plotting.compose_results(figure, results, *, panel_labels=True, shared_legends=True, owns_figure=False, theme=None)

Merge caller-targeted plot results into one inspectable figure result.

Return type:

PlotResult

cytearc.plotting.composition(store, *, category_by=None, categories=None, cell_key='I', sample_by=None, grouping=None, subject_by=None, pair_by=None, condition_by=None, study_design=None, kind='stacked', show_summary=True, uncertainty=None, categorical_scale=None, bar_width=0.82, bar_gap=0.12, segment_edgecolor=None, segment_linewidth=0.5, show_percent_labels=False, label_min_fraction=0.08, percent_format='{:.0%}', target=None, figsize=None, max_figure_width=7.5, theme='notebook', show_legend=True, show=True)

Show how cell categories (clusters, cell types) vary across samples.

kind="stacked" draws stacked bars. With sample_by, there is one bar per sample; without it, one bar for the whole dataset. grouping is the immutable artifact counterpart to sample_by for analytical groupings such as clusters. It is available only for stacked composition and must share the exact selection used by categories. kind="per_sample" draws one point per sample in each category (requires sample_by or a StudyDesign).

For paired before/after designs, pass condition_by together with subject_by or pair_by (directly or via study_design). CyteArc then connects the same subject across conditions inside each category. When a subject has several samples in one condition, those proportions are averaged for the connecting line. Per-sample plots show sample means with 95% confidence intervals by default. Use uncertainty to select standard deviation, standard error, or no interval.

Figure width is capped so large category lists stay page-sized.

Return type:

PlotResult

cytearc.plotting.distribution(store, keys, *, grouping=None, cell_selection=None, groups=None, split_by=None, sample_by=None, study_design=None, sample_stat='mean', expression_cutoff=0.0, subset_by=None, from_assay=None, normalization=None, categorical_scale=None, split_scale=None, kind='violin', bins=40, max_points=10000, point_size=0.8, point_alpha=0.28, seed=0, color='steelblue', color_by='group', color_scale=None, orientation='vertical', row_standardize=False, share_y=None, violin_inner='quartile', violin_linewidth=0.8, violin_alpha=0.9, italicize_features=False, target=None, figsize=None, max_figure_width=7.5, title=None, theme='notebook', show_legend=True, stats_results=None, stats_keys=None, stats_bracket_height=None, stats_show_p=True, show=True)

Compare value distributions for QC metrics or genes.

keys may be cell-metadata columns (for example RNA_nCounts), gene names, or one exact cell_cycle artifact. The artifact form plots its canonical s_score and g2m_score arrays. kind selects the display: "violin", "box", "hist", or "ecdf". With With grouping, each category gets its own distribution along the x-axis and a distinct color.

Cell selection (same knobs as embeddings):

• cell_selection: exact frozen selection; omit it to include every cell for metadata-backed values

• subset_by: boolean metadata column; keep True cells

• groups: keep or order grouping categories

For violins and boxes, CyteArc can overlay a subsample of cells as points. max_points limits how many points are drawn (0 disables points). The public default is 10000 for compatibility. Explicit None uses a kind-specific behavior: no overlay for stacked violins and 10000 for other kinds. Histograms always use every selected cell. Regular multi-gene violin and box panels share their value scale by default. Stacked violins keep independent scales unless share_y=True. With horizontal orientation, the same option shares the x-axis value scale.

Set sample_by or study_design to summarize cells within biological samples before plotting. A study design’s subject_by or pair_by column is used only with paired Wilcoxon stats_results, matching run_statistical_testing. split_by draws two violin halves for a second categorical variable.

Pass stats_results (a single StatisticalTestResult, or a mapping from panel label to one) to annotate significance brackets over the drawn violins or boxes. Brackets are pure matplotlib overlays positioned by the displayed category order; pairwise tables place one bracket per row, while one-way ANOVA and Kruskal-Wallis omnibus results span every group. A Dunn posthoc table is preferred over its Kruskal-Wallis omnibus table when both are present. The annotation prefers p_value_adjusted when present. Nothing is recomputed here. Results must carry the selection, grouping, tested-value, assay, sample-design, and normalization identity recorded by run_statistical_testing; incompatible or incomplete results are skipped with a warning. Statistical overlays cannot be combined with split_by.

For kind="stacked_violin", pass color_by="mean" to colour each stacked violin by its group mean expression on a continuous scale. Pass a ColorScale to control the mapping: cmap chooses the colormap, vmin/vmax fix explicit limits, quantiles clips extreme means, and vcenter enables diverging maps. The color scale follows share_y: scope="shared" when share_y=True and scope="panel" otherwise. ColorScale’s general scope="feature" default is treated as automatic here; explicit "shared" or "panel" overrides it. A scope="shared" scale is drawn as a colorbar on the right; scope="panel" rescales each row independently and draws a single reference colorbar. On caller-supplied axes the colorbar is not drawn; its limits are exposed through PlotResult.legends. color_by="mean" cannot be combined with split_by.

Raises:

ValueError – If a gene’s assay measured none of the plotted cells.

Return type:

PlotResult

cytearc.plotting.dotplot(store, *, features, group_by=None, groups=None, cell_key='I', from_assay=None, sample_by=None, study_design=None, normalization=None, expression_cutoff=0.0, standardize='none', color_scale=None, size_scale=None, categorical_scale=None, group_order=None, feature_order=None, swap_axes=False, marker_edgecolor=None, marker_linewidth=0.3, label_wrap=None, italicize_features=False, target=None, figsize=None, max_figure_width=7.5, theme='notebook', show_legend=True, show=True)

Dotplot of expression by group.

Color is the mean value in the group. Dot size is the fraction of measured cells above expression_cutoff. Pass features as a list of genes, or as a mapping of group name to gene list when you want gene-set brackets. Different features of one assay that carry the same explicit FeatureRef.label are pooled into one row. Any other label shared by different features raises, including a label shared across assays.

With sample_by (or study_design.sample_by), each sample contributes equally: CyteArc first summarizes within sample, then averages across samples. Without it, every cell contributes equally.

Return type:

PlotResult

cytearc.plotting.elbow(variance_explained, figsize=(None, 2), theme='notebook', show=True)

Plot explained variance and mark the detected elbow.

Return type:

PlotResult

cytearc.plotting.embedding(store, *, layout_key=None, layout=None, color_by=None, facet_by=None, facet_order=None, cell_key='I', from_assay=None, normalization=None, point_size=None, point_sizes=None, point_size_range=(1.0, 28.0), point_edgecolor=None, point_edgewidth=None, point_alpha=1.0, sort_values=False, color_scale=None, categorical_scale=None, default_color='steelblue', missing_color=None, clip_fraction=0.0, subset_by=None, groups=None, n_columns=None, target=None, figsize=None, theme='notebook', legend_loc='auto', max_on_data_labels=40, show_legend=True, show_titles=True, frame='minimal', density_overlay=None, highlight=None, seed=None, rasterize_threshold=50000, show=True)

Scatter cells on one or more 2D layouts (UMAP, t-SNE, and similar).

color_by accepts a cell-metadata column, a gene name, or a list of either. With several genes, CyteArc draws one panel per gene. With facet_by, each gene becomes a row and each facet level a column. Color limits for a gene are shared across facets so panels stay comparable. Multiple layout_key values produce the cartesian product of layouts and colors in one figure.

Common choices:

• subset_by: keep cells marked True in a boolean metadata column.

• groups: keep only these categories. Applies to facet_by when set, otherwise to the first categorical color_by column. Also sets legend order when categorical_scale.order is omitted.

• legend_loc: "auto" puts a side legend when there are few categories, labels on the clusters for medium category counts, and a wrapped side legend for larger sets. Use "right", "on_data", or "none" to force a placement.

• frame: "minimal" (default) keeps an L-shaped axes edge without UMAP tick labels. "none" removes the box. "axes" keeps UMAP1 / UMAP2 labels on the outer panels.

• point_size: leave as None to size markers from the cell count. Pass a number (matplotlib marker area) or point_sizes for per-cell sizes such as mapping confidence.

• sort_values=True: for continuous colors, draw high values last so expressing cells sit on top of the cloud.

• theme: "notebook" or "paper" for white figures; "dark" for dark notebook themes.

Returns a PlotResult. Access .figure in notebooks, or call .save(...) / .close() when you own the figure.

Return type:

PlotResult

cytearc.plotting.embedding_raster(store, *, layout_key=None, layout=None, color_by=None, cell_key='I', pixels=400, block_rows=None, color_scale=None, missing_color=None, subset_by=None, target=None, figsize=None, theme='notebook', seed=0, show=True)

Draw a layout as a pixel image for large cell counts.

Prefer this over embedding() when you only need a continuous cell-metadata color (for example RNA_nCounts) and the dataset is large enough that a full scatter is slow or memory-heavy. Values are read in row blocks, so full columns are not loaded at once.

Provide exactly one coordinate source. layout consumes an immutable embedding artifact and its stored cell selection. layout_key reads two explicit live metadata columns named {layout_key}1 and {layout_key}2.

color_by must be continuous metadata, not a gene. Pass CellField(key, kind="continuous") when an integer column should be treated as continuous. Categorical colors are not supported here. Empty pixels use a white background by default. Set ColorScale.missing_color or use missing_color as an explicit override. Pass subset_by to keep cells marked True in a boolean cell-metadata column.

Return type:

PlotResult

cytearc.plotting.graph_qc(graph, theme='notebook', show=True)

Plot node degree and edge weight distributions for a sparse graph.

Return type:

PlotResult

cytearc.plotting.highly_variable_features(mean_nonzero, corrected_variance, n_cells, selected, *, label_size=12, figsize=(4.5, 4.0), point_sizes=(3, 30), colormaps=('winter', 'magma_r'), theme='notebook', show=True)

Plot mean-variance diagnostics for feature selection.

Return type:

PlotResult

cytearc.plotting.label_panels(axes, *, labels=None, fontsize=None, fontweight='bold', x=-0.06, y=1.04)

Add A/B/C panel labels to axes in order.

Return type:

None

cytearc.plotting.mapping_calibration(store, transfer, *, known_labels, metric='voteFraction', direction='auto', thresholds=None, n_thresholds=50, chosen_threshold=None, target=None, figsize=None, theme='notebook', show=True)

Plot held-out label accuracy against retained coverage per threshold.

transfer is a label_transfer artifact from ds.mapping.transfer_labels. Each threshold on metric is applied to the transfer’s saved candidate labels, so no transfer is recomputed. The thresholds replace the transfer’s own rule on the swept metric, threshold_fraction for voteFraction and max_distance for nearestDistance, and every other saved rule still applies. Any other metric is therefore calibrated among the cells that the transfer labelled.

chosen_threshold is added to the thresholds and marked. Without it, the transfer’s own rule on the swept metric, when it has one, is marked: it joins the default thresholds, and with explicit thresholds it is marked only when it is one of them.

Return type:

PlotResult

cytearc.plotting.mapping_confusion(store, transfer, *, known_labels, normalize='true', known_order=None, predicted_order=None, abstention_label='Abstained', color_scale=None, target=None, figsize=None, theme='notebook', show_legend=True, show=True)

Plot known query labels against the labels of one saved transfer.

transfer is a label_transfer artifact from ds.mapping.transfer_labels. Cells that abstained form the abstention_label column, which must differ from every known and transferred label.

Return type:

PlotResult

cytearc.plotting.mapping_evidence(store, transfer, *, target_groups=None, metrics=('voteFraction', 'topTwoMargin', 'voteEntropy', 'referenceDistancePercentile'), kind='histogram', bins=30, categorical_scale=None, target=None, figsize=None, theme='notebook', show_legend=True, show=True)

Plot the saved evidence of one label transfer for query groups.

transfer is a label_transfer artifact from ds.mapping.transfer_labels. The plot reads its saved evidence, so it shows exactly the votes and distances that decided the saved labels.

Return type:

PlotResult

cytearc.plotting.mapping_score(store, result, *, reference, target_groups=None, layout=None, kind='embedding', reference_labels=None, size_by_score=False, log_transform=True, multiplier=1000, weighted=True, fixed_weight=0.1, bins=40, point_size=None, color_scale=None, categorical_scale=None, target=None, figsize=None, theme='notebook', show_legend=True, show=True)

Plot reference-cell mapping scores for one or more query groups.

kind="box" groups reference cells by reference_labels, a cell column or cell-label artifact of the reference datastore. Reference cells without a usable label are left out of the boxes.

Return type:

PlotResult

cytearc.plotting.marker_heatmap(store, *, marker, topn=5, log_transform=None, vmin=-1, vmax=2, figsize=None, fontsize=10, width_factor=0.03, height_factor=0.02, cmap='magma_r', color_scale=None, row_order=None, column_order=None, cluster_rows=True, cluster_columns=True, cluster_method='ward', cluster_metric='euclidean', row_annotations=None, column_annotations=None, annotation_scales=None, target=None, theme='notebook', show_legend=True, show=True, **heatmap_kwargs)

Plot standardized expression of the top marker features.

Return type:

PlotResult

cytearc.plotting.matrixplot(store, *, features, group_by=None, groups=None, cell_key='I', from_assay=None, sample_by=None, study_design=None, normalization=None, expression_cutoff=0.0, value='mean', standardize='none', color_scale=None, feature_order=None, group_order=None, cluster_features=False, cluster_groups=False, cluster_method='average', cluster_metric='euclidean', row_annotations=None, column_annotations=None, annotation_scales=None, target=None, figsize=None, theme='notebook', show_legend=True, show=True)

Heatmap of mean expression or detection fraction by group.

Rows follow the feature input order and columns follow the group order of dotplot(): a stored display order, otherwise natural order. Set explicit orders, compared as text, or enable hierarchical clustering independently for either axis. value="mean" colors by average expression; value="fraction" colors by the share of measured cells above expression_cutoff. standardize="feature" applies only to means. sample_by has the same equal-sample weighting behavior as dotplot(), and shared feature labels follow the same pooling rule.

Return type:

PlotResult

cytearc.plotting.modality_weights(store, *, graph, layout, point_size=None, point_alpha=1.0, cmap='viridis', n_columns=None, target=None, figsize=None, theme='notebook', frame='minimal', rasterize_threshold=50000, show=True)

Plot each assay’s WNN contribution over an explicit embedding.

Return type:

PlotResult

cytearc.plotting.pseudotime_heatmap(store, *, aggregation, show_features=None, feature_order=None, feature_cluster_order=None, figsize=(5, 10), vmin=-2.0, vmax=2.0, heatmap_cmap=None, pseudotime_cmap=None, clusterbar_cmap=None, color_scale=None, feature_cluster_scale=None, pseudotime_scale=None, tick_fontsize=10, axis_fontsize=12, feature_label_fontsize=12, target=None, theme='notebook', show_legend=True, show=True)

Plot binned feature dynamics ordered by pseudotime.

Return type:

PlotResult

cytearc.plotting.qc(data, color='steelblue', cmap='tab20', figsize=None, label_size=10.0, title_size=10, sup_title=None, sup_title_size=12, scatter_size=1.0, max_points=10000, seed=0, show_on_single_row=True, show=True, theme='notebook')

Plot grouped distributions for cell-level QC metrics.

Return type:

PlotResult

cytearc.plotting.run_recipe(store, recipe, *, artifacts=None, targets=None, output_dir=None, show=False, continue_on_error=False)

Run a plotting recipe’s steps in order after any analysis has completed.

Plots do not display themselves unless show is set.

Return type:

PlotRecipeResult

cytearc.plotting.theme_context(name='notebook')

Return type:

Iterator[None]

class cytearc.plotting.PlotResult(figure, axes, tables, legends, scales, provenance, owns_figure, theme='notebook')

Return value from cytearc.plotting functions.

figure is the matplotlib figure. axes maps panel keys to axes. tables holds any summary data used to build the plot. owns_figure is True when CyteArc created the figure. show() and close() release owned figures without discarding the result metadata.

save(path, *, dpi=None, transparent=False, exact_size=True, tiff_compression='tiff_lzw', provenance_sidecar=False)

Write the figure to disk (PNG, PDF, SVG, TIFF, and other backends).

The default background is opaque white for light themes and charcoal for the dark theme. Pass transparent=True when the destination supplies its own background. exact_size=True keeps the inch size you set when the figure was created; set it to False only when you want a tight crop for display. provenance_sidecar=True writes a sibling JSON file with the plot metadata.

Return type:

Path

save_provenance(path, *, figure_path=None, dpi=None)

Write a JSON file describing scales, legends, and cell counts.

Return type:

Path

class cytearc.plotting.FeatureRef(value, assay=None, by='name', label=None, reduction=None)

Reference to one assay feature.

Parameters:

• value (str | int) – Feature name, id, or physical index (see by).

• assay (str | None) – Assay name. Defaults to the store default assay when omitted.

• by (Literal['name', 'id', 'index']) – How to look up value: name, id, or index.

• label (str | None) – Optional display label.

• reduction (Optional[Literal['mean', 'sum']]) – Required when multiple features match; mean or sum.

class cytearc.plotting.CellField(key, kind='auto', label=None)

Point color_by or similar arguments at a cell-metadata column.

Use this when the column name alone is ambiguous. kind="categorical" forces discrete colors (useful for integer cluster ids). kind="continuous" forces a colorbar. kind="auto" chooses from the dtype and number of unique values.

class cytearc.plotting.StudyDesign(sample_by, condition_by=None, subject_by=None, pair_by=None, technical_replicate_by=None, technical_replicate_reduction=None)

Describe samples and conditions for composition and summary plots.

sample_by is the column that identifies biological samples. condition_by is the experimental condition (for example treatment). For paired composition plots, also set subject_by or pair_by so the same donor or pair can be connected across conditions.

class cytearc.plotting.NormalizationSpec(source='assay', transform='none')

How feature values are read for gene-colored plots.

source="assay" uses the assay’s current normalization settings. source="raw" reads raw counts. transform="log1p" applies log1p after that fetch, which is the usual choice for gene UMAPs and dotplots when you want a compressed expression scale. With source="assay" it needs a normalizer that supports log_transform.

class cytearc.plotting.ColorScale(cmap=None, vmin=None, vmax=None, vcenter=None, quantiles=None, missing_color='#bdbdbd', scope='feature', scale='linear')

Continuous color mapping for embeddings and summary plots.

Set vmin / vmax for fixed limits, or quantiles=(low, high) to ignore extreme tails (for example (0.0, 0.99) clips the top 1%). vcenter is for diverging maps such as scaled fold changes. scope controls whether limits are computed per feature (default), per panel, or shared across every continuous panel in the figure.

class cytearc.plotting.CategoricalScale(order=None, palette=None, labels=None, missing_color='#bdbdbd', missing_label='NA', palette_name='default')

Category order and colors for discrete embeddings and compositions.

order sets legend and axis order. palette maps each category to a color string. Categories missing from palette raise an error, so pass a complete map when you customize colors.

class cytearc.plotting.SizeScale(vmin=0.0, vmax=1.0, size_min=10.0, size_max=200.0)

Maps numeric values to marker area. Detection fraction uses domain [0, 1].

class cytearc.plotting.DensityOverlay(kind='line', statistic='density', pixels=160, sigma=2.0, min_support=0.25, levels=5, max_hotspots=None, group_by=None, groups=None, color=None, cmap=None, alpha=0.75, linewidth=0.8, halo_color=None, halo_width=0.0, zorder=4.0)

Contours drawn over an embedding.

group_by and groups optionally restrict the cells used to estimate the surface without changing the cells displayed underneath. statistic="mean" contours a smoothed local mean of the continuous panel values and attenuates pixels with less than min_support effective support. max_hotspots can retain only the strongest connected regions at the lowest contour level.

class cytearc.plotting.Highlight(by=None, groups=None, indices=None, color='#d62728', dim_alpha=0.12, alpha=1.0, size_multiplier=1.5, halo_color=None, halo_width=0.8)

Emphasize a metadata selection while retaining surrounding context.

class cytearc.plotting.PlotRecipe(steps)

An ordered collection of plotting steps.

class cytearc.plotting.PlotStep(name, plot, kwargs=<factory>, artifact_kwargs=<factory>, target=None, output=None, output_filename=None)

One named plotting call in a recipe.

class cytearc.plotting.PlotPanelTarget(panel)

Reference an axes supplied to the recipe runner by panel name.

class cytearc.plotting.PlotOutputSettings(filename, dpi=None, transparent=False, exact_size=True)

Per-step export settings resolved below the runner output directory.

class cytearc.plotting.PlotOutput(name, result, path=None)

The successful result of one recipe step.

class cytearc.plotting.PlotRecipeResult(outputs=(), written_paths=(), warnings=(), failures=<factory>)

Results and diagnostics from a recipe execution.

class cytearc.plotting.PlotProvenance(cytearc_version=<factory>, assay=None, cell_key=None, n_cells=0, n_samples=None, renderer='matplotlib', notes=(), extras=<factory>)

class cytearc.plotting.LegendSpec(kind, label=None, extras=<factory>)

Description of a legend or colorbar attached to a plot.

cytearc.plotting.THEMES

Registry of built-in plotting theme definitions.