smftools.plotting.hmm_plotting

Functions

combined_hmm_length_clustermap(adata[, ...])	Plot clustermaps for length-encoded HMM feature layers with optional subclass colors.
combined_hmm_raw_clustermap(adata[, ...])	Makes a multi-panel clustermap per (sample, reference):
plot_hmm_layers_rolling_by_sample_ref(adata)	For each sample (row) and reference (col) plot the rolling average of the positional mean (mean across reads) for each layer listed.
plot_hmm_size_contours(adata, length_layer, ...)	Create contour/pcolormesh plots of P(length | position) using a length-encoded HMM layer.

smftools.plotting.hmm_plotting.plot_hmm_size_contours(adata, length_layer, sample_col, ref_obs_col, rows_per_page=4, max_length_cap=1000, figsize_per_cell=(4.0, 2.5), cmap='viridis', log_scale_z=False, save_path=None, save_pdf=True, save_each_page=False, dpi=150, vmin=None, vmax=None, feature_ranges=None, zero_color='#eee6d9', nan_color='#D0D0D0', smoothing_sigma=None, normalize_after_smoothing=True, use_scipy_if_available=True, index_col_suffix=None)

Create contour/pcolormesh plots of P(length | position) using a length-encoded HMM layer. Optional Gaussian smoothing applied to the 2D probability grid before plotting. When feature_ranges is provided, each length row is assigned a base color based on the matching (min_len, max_len) range and the probability value modulates the color intensity.

smoothing_sigma: None or 0 -> no smoothing.

float -> same sigma applied to (length_axis, position_axis) (sigma_len, sigma_pos) -> separate sigmas.

normalize_after_smoothing:

if True, renormalize each position-column to sum to 1 after smoothing.

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

the x-axis position coordinate instead of var_names (per reference, since each reference's reindexed column can carry a different offset/ sign), falling back to var_names when the column is absent. pcolormesh doesn't require monotonic x, so no column reordering is needed here -- an inverted reference's signed coordinates render at their correct position automatically.

Other args are the same as prior function.

smftools.plotting.hmm_plotting.combined_hmm_raw_clustermap(adata, sample_col='Sample_Names', reference_col='Reference_strand', hmm_feature_layer='hmm_combined', layer_gpc='nan0_0minus1', layer_cpg='nan0_0minus1', layer_c='nan0_0minus1', layer_a='nan0_0minus1', cmap_hmm='tab10', cmap_gpc='coolwarm', cmap_cpg='viridis', cmap_c='coolwarm', cmap_a='coolwarm', min_quality=20, min_length=200, min_mapped_length_to_reference_length_ratio=0.8, min_position_valid_fraction=0.5, demux_types=('single', 'double', 'already'), sample_mapping=None, save_path=None, normalize_hmm=False, sort_by='gpc', bins=None, deaminase=False, min_signal=0.0, n_xticks_hmm=10, n_xticks_any_c=8, n_xticks_gpc=8, n_xticks_cpg=8, n_xticks_a=8, index_col_suffix=None, fill_nan_strategy='value', fill_nan_value=-1, overlay_variant_calls=False, variant_overlay_seq1_color='white', variant_overlay_seq2_color='black', variant_overlay_marker_size=4.0, omit_chimeric_reads=False, n_jobs=1, restrict_to_read_span=False, hmm_legend_labels=None, raw_legend_labels=None)

Makes a multi-panel clustermap per (sample, reference):

HMM panel (always) + optional raw panels for C, GpC, CpG, and A sites.

restrict_to_read_span: if True, crop each reference's plotted x-axis to [min(reference_start), max(reference_end)] across all QC-passing reads for that reference (union across every sample/barcode, computed once per reference so panels stay on a common x-axis for comparison), instead of the full reference length. No-op when reference_start/reference_end aren't present in adata.obs.

Panels are added only if the corresponding site mask exists AND has >0 sites.

sort_by options:

'gpc', 'cpg', 'c', 'a', 'gpc_cpg', 'none', 'hmm', or 'obs:<col>'

NaN fill strategy is applied in-memory for clustering/plotting only. omit_chimeric_reads: if True, exclude reads where chimeric_variant_sites==True. n_jobs: number of parallel worker processes (-1 = all CPUs).

smftools.plotting.hmm_plotting.combined_hmm_length_clustermap(adata, sample_col='Sample_Names', reference_col='Reference_strand', length_layer='hmm_combined_lengths', layer_gpc='nan0_0minus1', layer_cpg='nan0_0minus1', layer_c='nan0_0minus1', layer_a='nan0_0minus1', cmap_lengths='Greens', cmap_gpc='coolwarm', cmap_cpg='viridis', cmap_c='coolwarm', cmap_a='coolwarm', min_quality=20, min_length=200, min_mapped_length_to_reference_length_ratio=0.8, min_position_valid_fraction=0.5, demux_types=('single', 'double', 'already'), sample_mapping=None, save_path=None, sort_by='gpc', bins=None, deaminase=False, min_signal=0.0, n_xticks_lengths=10, n_xticks_any_c=8, n_xticks_gpc=8, n_xticks_cpg=8, n_xticks_a=8, index_col_suffix=None, fill_nan_strategy='value', fill_nan_value=-1, length_feature_ranges=None, overlay_variant_calls=False, variant_overlay_seq1_color='white', variant_overlay_seq2_color='black', variant_overlay_marker_size=4.0, omit_chimeric_reads=False, n_jobs=1, restrict_to_read_span=False)

Plot clustermaps for length-encoded HMM feature layers with optional subclass colors.

Length-based feature ranges map integer lengths into subclass colors for accessible and footprint layers. Raw methylation panels are included when available. omit_chimeric_reads: if True, exclude reads where chimeric_variant_sites==True. n_jobs: number of parallel worker processes (-1 = all CPUs). restrict_to_read_span: if True, crop each reference's plotted x-axis to [min(reference_start), max(reference_end)] across all QC-passing reads for that reference (union across every sample/barcode), instead of the full reference length. No-op when reference_start/reference_end aren't present in adata.obs.

smftools.plotting.hmm_plotting.plot_hmm_layers_rolling_by_sample_ref(adata, layers=None, sample_col='Barcode', ref_col='Reference_strand', samples=None, references=None, window=51, min_periods=1, center=True, rows_per_page=6, figsize_per_cell=(4.0, 2.5), dpi=160, output_dir=None, save=True, show_raw=False, cmap='tab20', layer_colors=None, use_var_coords=True, reindexed_var_suffix='reindexed')

For each sample (row) and reference (col) plot the rolling average of the positional mean (mean across reads) for each layer listed.

Parameters

adataAnnData

Input annotated data (expects obs columns sample_col and ref_col).

layerslist[str] | None

Which adata.layers to plot. If None, attempts to autodetect layers whose matrices look like "HMM" outputs (else will error). If None and layers cannot be found, user must pass a list.

sample_col, ref_colstr

obs columns used to group rows.

samples, referencesoptional lists

explicit ordering of samples / references. If None, categories in adata.obs are used.

windowint

rolling window size (odd recommended). If window <= 1, no smoothing applied.

min_periodsint

min periods param for pd.Series.rolling.

centerbool

center the rolling window.

rows_per_pageint

paginate rows per page into multiple figures if needed.

figsize_per_cell(w,h)

per-subplot size in inches.

dpiint

figure dpi when saving.

output_dirstr | None

directory to save pages; created if necessary. If None and save=True, uses cwd.

savebool

whether to save PNG files.

show_rawbool

draw unsmoothed mean as faint line under smoothed curve.

cmapstr

matplotlib colormap for layer lines.

layer_colorsdict[str, Any] | None

Optional mapping of layer name to explicit line colors.

use_var_coordsbool

if True, tries to use adata.var_names (coerced to int) as x-axis coordinates; otherwise uses 0..n-1.

reindexed_var_suffixstr

Suffix for per-reference reindexed var columns (e.g., Reference_reindexed) used when available.

Returns

saved_fileslist[str]

list of saved filenames (may be empty if save=False).