smftools.plotting.chimeric_plotting

smftools.plotting.chimeric_plotting#

Functions

`plot_delta_hamming_summary`(subset[, ...])	Plot a 2×3 summary: row 1 = self NN, cross NN, signal layer; row 2 = self hamming spans, cross hamming spans, delta hamming spans.
`plot_hamming_span_trio`(subset[, ...])	Plot a 1×3 trio of hamming span clustermaps (self, cross, delta) with no column subsetting, optionally overlaying variant call circles.
`plot_rolling_nn_and_layer`(subset[, ...])
`plot_rolling_nn_and_two_layers`(subset[, ...])	Plot rolling NN distances alongside two layer clustermaps.
`plot_segment_length_histogram`(raw_lengths, ...)	Plot an overlay histogram of segment lengths for raw vs filtered spans.
`plot_span_length_distributions`(subset[, ...])	Overlay probability histograms of contiguous span lengths from three layers.
`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.chimeric_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', nn_nan_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)#

Cluster rows by subset.obsm[obsm_key] (rolling NN distances)
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.
nn_nan_color (str (default: '#bdbdbd')) -- Color used for NaNs in the rolling NN heatmap.
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.chimeric_plotting.plot_rolling_nn_and_two_layers(subset, obsm_key='rolling_nn_dist', layer_keys=('nan0_0minus1', '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', nn_nan_color='#bdbdbd', figsize=(20, 10), layer_var_mask=None, robust=True, title=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=8, save_name=None)#

Plot rolling NN distances alongside two layer clustermaps.

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_keys (Sequence[str] (default: ('nan0_0minus1', 'nan0_0minus1'))) -- Two layer names 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 heatmaps 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.
nn_nan_color (str (default: '#bdbdbd')) -- Color used for NaNs in the rolling NN heatmap.
figsize (tuple[float, float] (default: (20, 10))) -- Figure size for the combined plot.
layer_var_mask (default: None) -- Optional boolean mask over subset.var for the layer panels.
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.chimeric_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, variant_call_data=None, seq1_label='seq1', seq2_label='seq2', ref1_marker_color='white', ref2_marker_color='black', variant_marker_size=4.0, 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.
variant_call_data (DataFrame | None (default: None)) -- Optional DataFrame (obs × full var_names) with variant calls (1=seq1, 2=seq2). When provided, circles are overlaid at positions that overlap with the plotted columns. Built from the full-width adata before column filtering so mismatch sites outside modification sites are mapped.
seq1_label (str (default: 'seq1')) -- Label for seq1 in the legend.
seq2_label (str (default: 'seq2')) -- Label for seq2 in the legend.
ref1_marker_color (str (default: 'white')) -- Circle color for seq1 variant calls.
ref2_marker_color (str (default: 'black')) -- Circle color for seq2 variant calls.
variant_marker_size (float (default: 4.0)) -- Size of variant call overlay circles.
save_name (str | None (default: None)) -- Optional output path for saving the plot.

smftools.plotting.chimeric_plotting.plot_delta_hamming_summary(subset, self_obsm_key='rolling_nn_dist', cross_obsm_key='rolling_nn_dist', layer_key='nan0_0minus1', self_span_layer_key='zero_hamming_distance_spans', cross_span_layer_key='cross_sample_zero_hamming_distance_spans', delta_span_layer_key='delta_zero_hamming_distance_spans', meta_cols=('Reference_strand', 'Sample'), col_cluster=False, fill_nn_with_colmax=True, fill_layer_value=0.0, fill_span_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', nn_nan_color='#bdbdbd', span_color='#2ca25f', cross_span_color='#e6550d', delta_span_color='#756bb1', figsize=(30, 24), robust=True, title=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=8, save_name=None)#

Plot a 2×3 summary: row 1 = self NN, cross NN, signal layer; row 2 = self hamming spans, cross hamming spans, delta hamming spans.

Cluster order is determined by the delta hamming span layer. Barplots are drawn above each clustermap.

Parameters:

subset -- AnnData subset with all required obsm/layers.
self_obsm_key (str (default: 'rolling_nn_dist')) -- obsm key for within-sample rolling NN distances.
cross_obsm_key (str (default: 'rolling_nn_dist')) -- obsm key for cross-sample rolling NN distances.
layer_key (str (default: 'nan0_0minus1')) -- Signal layer to plot in top-right panel.
self_span_layer_key (str (default: 'zero_hamming_distance_spans')) -- Layer with within-sample zero-Hamming spans.
cross_span_layer_key (str (default: 'cross_sample_zero_hamming_distance_spans')) -- Layer with cross-sample zero-Hamming spans.
delta_span_layer_key (str (default: 'delta_zero_hamming_distance_spans')) -- Layer with delta (self - cross) zero-Hamming spans.
meta_cols (tuple[str, ...] (default: ('Reference_strand', 'Sample'))) -- Obs columns for row color annotations.
col_cluster (bool (default: False)) -- Cluster columns.
fill_nn_with_colmax (bool (default: True)) -- Fill NN NaNs with per-column max for display.
fill_layer_value (float (default: 0.0)) -- Fill NaN in signal layer.
fill_span_value (float (default: 0.0)) -- Fill NaN in span layers.
drop_all_nan_windows (bool (default: True)) -- Drop all-NaN rolling NN windows.
max_nan_fraction (float | None (default: None)) -- Max NaN fraction filter for layer columns.
var_valid_fraction_col (str | None (default: None)) -- Var column with valid fraction.
var_nan_fraction_col (str | None (default: None)) -- Var column with NaN fraction.
read_span_layer (str | None (default: 'read_span_mask')) -- Layer with read span mask.
outside_read_color (str (default: '#bdbdbd')) -- Color for outside-read positions.
nn_nan_color (str (default: '#bdbdbd')) -- Color for NaN in NN heatmaps.
span_color (str (default: '#2ca25f')) -- Color for self hamming span (1 values).
cross_span_color (str (default: '#e6550d')) -- Color for cross hamming span (1 values).
delta_span_color (str (default: '#756bb1')) -- Color for delta hamming span (1 values).
figsize (tuple[float, float] (default: (30, 24))) -- Figure size.
robust (bool (default: True)) -- Robust color scaling.
title (str | None (default: None)) -- Figure suptitle.
xtick_step (int | None (default: None)) -- Spacing between x-tick labels.
xtick_rotation (int (default: 90)) -- X-tick label rotation.
xtick_fontsize (int (default: 8)) -- X-tick label font size.
save_name (str | None (default: None)) -- Output path.

smftools.plotting.chimeric_plotting.plot_span_length_distributions(subset, self_span_layer_key='zero_hamming_distance_spans', cross_span_layer_key='cross_sample_zero_hamming_distance_spans', delta_span_layer_key='delta_zero_hamming_distance_spans', read_span_layer='read_span_mask', bins=30, self_color='#2ca25f', cross_color='#e6550d', delta_color='#756bb1', figsize=(10, 6), title=None, save_name=None)#

Overlay probability histograms of contiguous span lengths from three layers.

Span length is measured in base-pair coordinates using subset.var_names. Positions outside the valid read span (where read_span_layer == 0) are excluded before detecting contiguous runs.

Parameters:

subset -- AnnData subset containing the span layers.
self_span_layer_key (str (default: 'zero_hamming_distance_spans')) -- Layer with within-sample zero-Hamming spans.
cross_span_layer_key (str (default: 'cross_sample_zero_hamming_distance_spans')) -- Layer with cross-sample zero-Hamming spans.
delta_span_layer_key (str (default: 'delta_zero_hamming_distance_spans')) -- Layer with delta (self - cross) spans.
read_span_layer (str | None (default: 'read_span_mask')) -- Layer with read span mask; 0 = outside read.
bins (int (default: 30)) -- Number of histogram bins.
self_color (str (default: '#2ca25f')) -- Histogram color for self spans.
cross_color (str (default: '#e6550d')) -- Histogram color for cross spans.
delta_color (str (default: '#756bb1')) -- Histogram color for delta spans.
figsize (tuple[float, float] (default: (10, 6))) -- Figure size.
title (str | None (default: None)) -- Figure title.
save_name (str | None (default: None)) -- Output path.

smftools.plotting.chimeric_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.chimeric_plotting.plot_segment_length_histogram(raw_lengths, filtered_lengths, bins=30, title=None, raw_label='All segments', filtered_label='Filtered segments', figsize=(8, 4), density=True, save_name=None)#

Plot an overlay histogram of segment lengths for raw vs filtered spans.

Parameters:

raw_lengths (ndarray) -- Array of raw segment lengths.
filtered_lengths (ndarray) -- Array of filtered segment lengths.
bins (int (default: 30)) -- Number of histogram bins.
title (str | None (default: None)) -- Optional plot title.
raw_label (str (default: 'All segments')) -- Label for raw segment histogram.
filtered_label (str (default: 'Filtered segments')) -- Label for filtered segment histogram.
figsize (tuple[float, float] (default: (8, 4))) -- Size of the matplotlib figure.
density (bool (default: True)) -- If True, plot probabilities instead of counts.
save_name (str | None (default: None)) -- Optional output path for saving the plot.

smftools.plotting.chimeric_plotting.plot_hamming_span_trio(subset, self_span_layer_key='zero_hamming_distance_spans', cross_span_layer_key='cross_sample_zero_hamming_distance_spans', delta_span_layer_key='delta_zero_hamming_distance_spans', read_span_layer='read_span_mask', outside_read_color='#bdbdbd', span_color='#2ca25f', cross_span_color='#e6550d', delta_span_color='#756bb1', figsize=(16, 8), robust=True, title=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=8, variant_call_data=None, seq1_label='seq1', seq2_label='seq2', ref1_marker_color='white', ref2_marker_color='black', variant_marker_size=4.0, classification_obs_col='chimeric_by_mod_hamming_distance', classification_true_color='#000000', classification_false_color='#f0f0f0', classification_panel_title='Mod-hamming chimera', save_name=None)#

Plot a 1×3 trio of hamming span clustermaps (self, cross, delta) with no column subsetting, optionally overlaying variant call circles.

Row order is determined by hierarchical clustering on the delta span layer. A barplot showing per-column mean span fraction is drawn above each panel.

smftools.plotting.chimeric_plotting

Contents

smftools.plotting.chimeric_plotting#