smftools.plotting.spatial_plotting

smftools.plotting.spatial_plotting#

Functions

combined_raw_clustermap(adata[, sample_col, ...])

Plot stacked heatmaps + per-position mean barplots for C, GpC, CpG, and optional A.

plot_rolling_nn_and_layer(subset[, ...])

plot_zero_hamming_pair_counts(subset, ...[, ...])

Plot a heatmap of zero-Hamming pair counts per read across rolling windows.

plot_zero_hamming_span_and_layer(subset, ...)

Plot zero-Hamming span clustermap alongside a layer clustermap.
smftools.plotting.spatial_plotting.plot_rolling_nn_and_layer(subset, obsm_key='rolling_nn_dist', layer_key='nan0_0minus1', meta_cols=('Reference_strand', 'Sample'), col_cluster=False, fill_nn_with_colmax=True, fill_layer_value=0.0, drop_all_nan_windows=True, max_nan_fraction=None, var_valid_fraction_col=None, var_nan_fraction_col=None, read_span_layer='read_span_mask', outside_read_color='#bdbdbd', figsize=(14, 10), right_panel_var_mask=None, robust=True, title=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=8, save_name=None)#

  1. Cluster rows by subset.obsm[obsm_key] (rolling NN distances)

  2. Plot two heatmaps side-by-side in the SAME row order, with mean barplots above:

    • left: rolling NN distance matrix

    • right: subset.layers[layer_key] matrix

Handles categorical/MultiIndex issues in metadata coloring.

Parameters:

  • subset -- AnnData subset with rolling NN distances stored in obsm.

  • obsm_key (str (default: 'rolling_nn_dist')) -- Key in subset.obsm containing rolling NN distances.

  • layer_key (str (default: 'nan0_0minus1')) -- Layer name to plot alongside rolling NN distances.

  • meta_cols (tuple[str, ...] (default: ('Reference_strand', 'Sample'))) -- Obs columns used for row color annotations.

  • col_cluster (bool (default: False)) -- Whether to cluster columns in the rolling NN clustermap.

  • fill_nn_with_colmax (bool (default: True)) -- Fill NaNs in rolling NN distances with per-column max values.

  • fill_layer_value (float (default: 0.0)) -- Fill NaNs in the layer heatmap with this value.

  • drop_all_nan_windows (bool (default: True)) -- Drop rolling windows that are all NaN.

  • max_nan_fraction (float | None (default: None)) -- Maximum allowed NaN fraction per position (filtering columns).

  • var_valid_fraction_col (str | None (default: None)) -- subset.var column with valid fractions (1 - NaN fraction).

  • var_nan_fraction_col (str | None (default: None)) -- subset.var column with NaN fractions.

  • read_span_layer (str | None (default: 'read_span_mask')) -- Layer name with read span mask; 0 values are treated as outside read.

  • outside_read_color (str (default: '#bdbdbd')) -- Color used to show positions outside each read.

  • figsize (tuple[float, float] (default: (14, 10))) -- Figure size for the combined plot.

  • right_panel_var_mask (default: None) -- Optional boolean mask over subset.var for the right panel.

  • robust (bool (default: True)) -- Use robust color scaling in seaborn.

  • title (str | None (default: None)) -- Optional figure title (suptitle).

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

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

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

  • save_name (str | None (default: None)) -- Optional output path for saving the plot.

smftools.plotting.spatial_plotting.plot_zero_hamming_span_and_layer(subset, span_layer_key, layer_key='nan0_0minus1', meta_cols=('Reference_strand', 'Sample'), col_cluster=False, fill_span_value=0.0, fill_layer_value=0.0, drop_all_nan_positions=True, max_nan_fraction=None, var_valid_fraction_col=None, var_nan_fraction_col=None, read_span_layer='read_span_mask', outside_read_color='#bdbdbd', span_color='#2ca25f', figsize=(14, 10), robust=True, title=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=8, save_name=None)#

Plot zero-Hamming span clustermap alongside a layer clustermap.

Parameters:

  • subset -- AnnData subset with zero-Hamming span annotations stored in layers.

  • span_layer_key (str) -- Layer name with the binary zero-Hamming span mask.

  • layer_key (str (default: 'nan0_0minus1')) -- Layer name to plot alongside the span mask.

  • meta_cols (tuple[str, ...] (default: ('Reference_strand', 'Sample'))) -- Obs columns used for row color annotations.

  • col_cluster (bool (default: False)) -- Whether to cluster columns in the span mask clustermap.

  • fill_span_value (float (default: 0.0)) -- Value to fill NaNs in the span mask.

  • fill_layer_value (float (default: 0.0)) -- Value to fill NaNs in the layer heatmap.

  • drop_all_nan_positions (bool (default: True)) -- Drop positions that are all NaN in the span mask.

  • max_nan_fraction (float | None (default: None)) -- Maximum allowed NaN fraction per position (filtering columns).

  • var_valid_fraction_col (str | None (default: None)) -- subset.var column with valid fractions (1 - NaN fraction).

  • var_nan_fraction_col (str | None (default: None)) -- subset.var column with NaN fractions.

  • read_span_layer (str | None (default: 'read_span_mask')) -- Layer name with read span mask; 0 values are treated as outside read.

  • outside_read_color (str (default: '#bdbdbd')) -- Color used to show positions outside each read.

  • span_color (str (default: '#2ca25f')) -- Color for zero-Hamming span mask values.

  • figsize (tuple[float, float] (default: (14, 10))) -- Figure size for the combined plot.

  • robust (bool (default: True)) -- Use robust color scaling in seaborn.

  • title (str | None (default: None)) -- Optional figure title (suptitle).

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

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

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

  • save_name (str | None (default: None)) -- Optional output path for saving the plot.

smftools.plotting.spatial_plotting.plot_zero_hamming_pair_counts(subset, zero_pairs_uns_key, meta_cols=('Reference_strand', 'Sample'), col_cluster=False, figsize=(14, 10), robust=True, title=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=8, save_name=None)#

Plot a heatmap of zero-Hamming pair counts per read across rolling windows.

Parameters:

  • subset -- AnnData subset containing zero-pair window data in .uns.

  • zero_pairs_uns_key (str) -- Key in subset.uns with zero-pair window data.

  • meta_cols (tuple[str, ...] (default: ('Reference_strand', 'Sample'))) -- Obs columns used for row color annotations.

  • col_cluster (bool (default: False)) -- Whether to cluster columns in the heatmap.

  • figsize (tuple[float, float] (default: (14, 10))) -- Figure size for the plot.

  • robust (bool (default: True)) -- Use robust color scaling in seaborn.

  • title (str | None (default: None)) -- Optional figure title (suptitle).

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

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

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

  • save_name (str | None (default: None)) -- Optional output path for saving the plot.

smftools.plotting.spatial_plotting.combined_raw_clustermap(adata, sample_col='Sample_Names', reference_col='Reference_strand', mod_target_bases=('GpC', 'CpG'), layer_c='nan0_0minus1', layer_gpc='nan0_0minus1', layer_cpg='nan0_0minus1', layer_a='nan0_0minus1', cmap_c='coolwarm', cmap_gpc='coolwarm', cmap_cpg='viridis', cmap_a='coolwarm', min_quality=20, min_length=200, min_mapped_length_to_reference_length_ratio=0, min_position_valid_fraction=0, demux_types=('single', 'double', 'already'), sample_mapping=None, save_path=None, sort_by='gpc', bins=None, deaminase=False, min_signal=0, n_xticks_any_c=10, n_xticks_gpc=10, n_xticks_cpg=10, n_xticks_any_a=10, xtick_rotation=90, xtick_fontsize=9, index_col_suffix=None, fill_nan_strategy='value', fill_nan_value=-1, n_jobs=1, omit_chimeric_reads=False, restrict_to_read_span=False)#

Plot stacked heatmaps + per-position mean barplots for C, GpC, CpG, and optional A.

Key fixes vs old version:

  • order computed ONCE per bin, applied to all matrices

  • no hard-coded axes indices

  • NaNs excluded from methylation denominators

  • var_names not forced to int

  • fixed count of x tick labels per block (controllable)

  • optional NaN fill strategy for clustering/plotting (in-memory only)

  • adata.uns updated once at end

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 -- not per-sample -- so every sample's plot for a given reference stays on the same x-axis for visual comparison), instead of the full reference length. No-op when reference_start/reference_end aren't present in adata.obs.

Returns#

resultslist[dict]

One entry per (sample, ref) plot with output metadata.