Source: https://docs.nygen.io/CyteArc/api/plotting.html Revision: fccee7b6e0c167e47ce605c8d292fba5b567ebfe 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 | "mapping_evidence(transfer_ref)", | | calibration | "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 "_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=, artifact_kwargs=, 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=) Results and diagnostics from a recipe execution. class cytearc.plotting.PlotProvenance(cytearc_version=, assay=None, cell_key=None, n_cells=0, n_samples=None, renderer='matplotlib', notes=(), extras=) class cytearc.plotting.LegendSpec(kind, label=None, extras=) Description of a legend or colorbar attached to a plot. cytearc.plotting.THEMES Registry of built-in plotting theme definitions.