smftools.plotting.variant_plotting

Functions

plot_mismatch_base_frequency_by_position(adata)	Plot mismatch base frequencies by position per sample/reference.
plot_sequence_integer_encoding_clustermaps(adata)	Plot integer-encoded sequence clustermaps per sample/reference.
plot_variant_segment_clustermaps(adata, ...)	Plot variant segment heatmaps with variant call and breakpoint overlays.
plot_variant_segment_clustermaps_multi_obs(...)	Plot variant segment clustermaps with multiple adjacent categorical strips.

smftools.plotting.variant_plotting.plot_mismatch_base_frequency_by_position(adata, sample_col='Sample_Names', reference_col='Reference_strand', mismatch_layer='mismatch_integer_encoding', read_span_layer='read_span_mask', quality_layer='base_quality_scores', plot_zscores=False, exclude_mod_sites=False, mod_site_bases=None, min_quality=None, min_length=None, min_mapped_length_to_reference_length_ratio=None, demux_types=('single', 'double', 'already'), save_path=None)

Plot mismatch base frequencies by position per sample/reference.

Parameters:

• adata -- AnnData with mismatch integer encoding layer.

• sample_col (str (default: 'Sample_Names')) -- Column in adata.obs that identifies samples.

• reference_col (str (default: 'Reference_strand')) -- Column in adata.obs that identifies references.

• mismatch_layer (str (default: 'mismatch_integer_encoding')) -- Layer name containing mismatch integer encodings.

• read_span_layer (str (default: 'read_span_mask')) -- Layer name containing read-span masks.

• quality_layer (str (default: 'base_quality_scores')) -- Layer name containing base-quality scores used for z-scores.

• plot_zscores (bool (default: False)) -- Whether to plot quality-normalized z-scores in a separate panel.

• exclude_mod_sites (bool (default: False)) -- Whether to exclude annotated modification sites.

• mod_site_bases (Optional[Sequence[str]] (default: None)) -- Base-context labels used to build mod-site masks (e.g., ["GpC", "CpG"]).

• min_quality (float | None (default: None)) -- Optional minimum read quality filter.

• min_length (int | None (default: None)) -- Optional minimum mapped length filter.

• min_mapped_length_to_reference_length_ratio (float | None (default: None)) -- Optional min length ratio filter.

• demux_types (Sequence[str] (default: ('single', 'double', 'already'))) -- Allowed demux_type values, if present in adata.obs.

• save_path (str | Path | None (default: None)) -- Optional output directory for saving plots.

Return type:

List[Dict[str, Any]]

Returns:

List of dictionaries with per-plot metadata and output paths. Includes a pooled-samples entry per reference.

smftools.plotting.variant_plotting.plot_sequence_integer_encoding_clustermaps(adata, sample_col='Sample_Names', reference_col='Reference_strand', layer='sequence_integer_encoding', mismatch_layer='mismatch_integer_encoding', exclude_mod_sites=False, mod_site_bases=None, min_quality=20, min_length=200, min_mapped_length_to_reference_length_ratio=0, demux_types=('single', 'double', 'already'), sort_by='none', cmap='viridis', max_unknown_fraction=None, unknown_values=(4, 5), xtick_step=None, xtick_rotation=90, xtick_fontsize=9, max_reads=None, save_path=None, use_dna_5color_palette=True, show_numeric_colorbar=False, show_position_axis=False, position_axis_tick_target=25, n_jobs=1, index_col_suffix=None)

Plot integer-encoded sequence clustermaps per sample/reference.

Parameters:

• adata -- AnnData with a sequence_integer_encoding layer.

• sample_col (str (default: 'Sample_Names')) -- Column in adata.obs that identifies samples.

• reference_col (str (default: 'Reference_strand')) -- Column in adata.obs that identifies references.

• layer (str (default: 'sequence_integer_encoding')) -- Layer name containing integer-encoded sequences.

• mismatch_layer (str (default: 'mismatch_integer_encoding')) -- Optional layer name containing mismatch integer encodings.

• exclude_mod_sites (bool (default: False)) -- Whether to exclude annotated modification sites.

• mod_site_bases (Optional[Sequence[str]] (default: None)) -- Base-context labels used to build mod-site masks (e.g., ["GpC", "CpG"]).

• min_quality (float | None (default: 20)) -- Optional minimum read quality filter.

• min_length (int | None (default: 200)) -- Optional minimum mapped length filter.

• min_mapped_length_to_reference_length_ratio (float | None (default: 0)) -- Optional min length ratio filter.

• demux_types (Sequence[str] (default: ('single', 'double', 'already'))) -- Allowed demux_type values, if present in adata.obs.

• sort_by (str (default: 'none')) -- Row sorting strategy: none, hierarchical, or obs:<col>.

• cmap (str (default: 'viridis')) -- Matplotlib colormap for the heatmap when use_dna_5color_palette is False.

• max_unknown_fraction (float | None (default: None)) -- Optional maximum fraction of unknown_values allowed per position; positions above this threshold are excluded.

• unknown_values (Sequence[int] (default: (4, 5))) -- Integer values to treat as unknown/padding.

• xtick_step (int | None (default: None)) -- Spacing between x-axis tick labels (None = no labels).

• xtick_rotation (int (default: 90)) -- Rotation for x-axis tick labels.

• xtick_fontsize (int (default: 9)) -- Font size for x-axis tick labels.

• max_reads (int | None (default: None)) -- Optional maximum number of reads to plot per sample/reference.

• save_path (str | Path | None (default: None)) -- Optional output directory for saving plots.

• use_dna_5color_palette (bool (default: True)) -- Whether to use a fixed A/C/G/T/Other palette.

• show_numeric_colorbar (bool (default: False)) -- If False, use a legend instead of a numeric colorbar.

• show_position_axis (bool (default: False)) -- Whether to draw a position axis with tick labels.

• position_axis_tick_target (int (default: 25)) -- Approximate number of ticks to show when auto-sizing.

• n_jobs (int (default: 1)) -- Number of parallel worker processes. -1 uses all available CPUs. Parallelism is only applied when save_path is set.

• index_col_suffix (str | None (default: None)) -- If set, use adata.var[f"{ref}_{index_col_suffix}"] for tick labels and column order instead of var_names (e.g. "reindexed"), matching the HMM/spatial clustermaps.

Returns:

List of dictionaries with per-plot metadata and output paths.

smftools.plotting.variant_plotting.plot_variant_segment_clustermaps(adata, seq1_column, seq2_column, sample_col='Sample_Names', reference_col='Reference_strand', variant_segment_layer=None, read_span_layer='read_span_mask', sort_by='hierarchical', max_reads=None, save_path=None, seq1_color='#8B5CF6', seq2_color='#4682b4', transition_color='#F5F5DC', no_coverage_color='#f0f0f0', ref1_marker_color='white', ref2_marker_color='black', breakpoint_marker_color='red', marker_size=4.0, show_position_axis=False, position_axis_tick_target=25, xtick_rotation=90, xtick_fontsize=9, mismatch_type_obs_col=None, mismatch_type_colors=None, mismatch_type_legend_prefix='Mismatch type', n_jobs=1, index_col_suffix=None)

Plot variant segment heatmaps with variant call and breakpoint overlays.

Renders per-read segment blocks (seq1/seq2) as colored fills with beige transition zones between different-class blocks. Overlays white circles at seq1 variant call sites, black circles at seq2 sites, and red circles at putative breakpoint positions (midpoint of each transition zone).

Parameters:

• adata -- AnnData object.

• seq1_column (str) -- Name of reference 1 sequence column in adata.var.

• seq2_column (str) -- Name of reference 2 sequence column in adata.var.

• sample_col (str (default: 'Sample_Names')) -- Obs column for sample grouping.

• reference_col (str (default: 'Reference_strand')) -- Obs column for reference grouping.

• variant_segment_layer (str | None (default: None)) -- Layer with variant segments (0=no coverage, 1=seq1, 2=seq2, 3=transition zone). Auto-derived if None.

• read_span_layer (str (default: 'read_span_mask')) -- Layer containing read span masks.

• sort_by (str (default: 'hierarchical')) -- Row sorting strategy — "none" or "hierarchical".

• max_reads (int | None (default: None)) -- Maximum reads to display per panel.

• save_path (str | Path | None (default: None)) -- Directory to save plots. If None, displays interactively.

• seq1_color (str (default: '#8B5CF6')) -- Fill color for seq1 segments.

• seq2_color (str (default: '#4682b4')) -- Fill color for seq2 segments.

• transition_color (str (default: '#F5F5DC')) -- Fill color for transition zones between blocks.

• no_coverage_color (str (default: '#f0f0f0')) -- Fill color for positions with no coverage.

• ref1_marker_color (str (default: 'white')) -- Circle color for seq1 variant call positions.

• ref2_marker_color (str (default: 'black')) -- Circle color for seq2 variant call positions.

• breakpoint_marker_color (str (default: 'red')) -- Circle color for putative breakpoint positions.

• marker_size (float (default: 4.0)) -- Size of overlay circles.

• show_position_axis (bool (default: False)) -- Whether to show genomic position labels on x-axis.

• position_axis_tick_target (int (default: 25)) -- Target number of x-axis ticks.

• xtick_rotation (int (default: 90)) -- Rotation angle for x-axis tick labels.

• xtick_fontsize (int (default: 9)) -- Font size for x-axis tick labels.

• mismatch_type_obs_col (str | None (default: None)) -- Optional obs column to annotate per read as an adjacent categorical strip.

• mismatch_type_colors (Optional[Dict[str, str]] (default: None)) -- Optional mapping from mismatch class label to color. Missing labels fall back to gray.

• mismatch_type_legend_prefix (str (default: 'Mismatch type')) -- Prefix used in legend entries for the mismatch/categorical annotation (e.g., "Mismatch type" or "UMI content").

• index_col_suffix (str | None (default: None)) -- If set, use adata.var[f"{ref}_{index_col_suffix}"] for tick labels and column order instead of var_names (e.g. "reindexed"), matching the HMM/spatial clustermaps.

Return type:

List[Dict[str, Any]]

Returns:

List of dicts with metadata about each generated plot.

smftools.plotting.variant_plotting.plot_variant_segment_clustermaps_multi_obs(adata, seq1_column, seq2_column, sample_col='Sample_Names', reference_col='Reference_strand', variant_segment_layer=None, read_span_layer='read_span_mask', sort_by='hierarchical', max_reads=None, save_path=None, seq1_color='#8B5CF6', seq2_color='#4682b4', transition_color='#F5F5DC', no_coverage_color='#f0f0f0', ref1_marker_color='white', ref2_marker_color='black', breakpoint_marker_color='red', marker_size=4.0, show_position_axis=False, position_axis_tick_target=25, xtick_rotation=90, xtick_fontsize=9, annotation_specs=None, n_jobs=1, index_col_suffix=None)

Plot variant segment clustermaps with multiple adjacent categorical strips.

Each annotation strip is configured via annotation_specs entries: - obs_col (required): obs column with per-read labels. - colors (optional): dict label -> color. - legend_prefix (optional): prefix for legend labels. - strip_title (optional): title shown above strip. - n_jobs: Number of parallel worker processes (-1 = all CPUs).

Return type:

List[Dict[str, Any]]

index_col_suffix: If set, use adata.var[f"{ref}_{index_col_suffix}"]

for tick labels and column order instead of var_names (e.g. "reindexed"), matching the HMM/spatial clustermaps.