smftools.plotting.general_plotting

smftools.plotting.general_plotting#

smftools.plotting.general_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.general_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.general_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.

smftools.plotting.general_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.general_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.general_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.general_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.general_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.general_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).

smftools.plotting.general_plotting.plot_nmf_components(adata, *, output_dir, components_key='H_nmf', suffix=None, heatmap_name='heatmap.png', lineplot_name='lineplot.png', max_features=2000)#

Plot NMF component weights as a heatmap and per-component scatter plot.

Parameters:

adata (AnnData) -- AnnData object containing NMF results.
output_dir (Path | str) -- Directory to write plots into.
components_key (str (default: 'H_nmf')) -- Key in adata.varm storing the H matrix.
heatmap_name (str (default: 'heatmap.png')) -- Filename for the heatmap plot.
lineplot_name (str (default: 'lineplot.png')) -- Filename for the scatter plot.
max_features (int (default: 2000)) -- Maximum number of features to plot (top-weighted by component).

Returns:

Paths to created plots (keys: heatmap and lineplot).

Return type:

Dict[str, Path]

smftools.plotting.general_plotting.plot_pca_components(adata, *, output_dir, components_key='PCs', suffix=None, heatmap_name='heatmap.png', lineplot_name='lineplot.png', max_features=2000)#

Plot PCA component loadings as a heatmap and per-component scatter plot.

Parameters:

adata (AnnData) -- AnnData object containing PCA results.
output_dir (Path | str) -- Directory to write plots into.
components_key (str (default: 'PCs')) -- Key in adata.varm storing the components.
heatmap_name (str (default: 'heatmap.png')) -- Filename for the heatmap plot.
lineplot_name (str (default: 'lineplot.png')) -- Filename for the scatter plot.
max_features (int (default: 2000)) -- Maximum number of features to plot (top-weighted by component).

Returns:

Paths to created plots (keys: heatmap and lineplot).

Return type:

Dict[str, Path]

smftools.plotting.general_plotting.plot_cp_sequence_components(adata, *, output_dir, components_key='H_cp_sequence', uns_key='cp_sequence', base_factors_key=None, suffix=None, heatmap_name='cp_sequence_position_heatmap.png', lineplot_name='cp_sequence_position_lineplot.png', base_factors_name='cp_sequence_base_weights.png', max_positions=2000)#

Plot CP sequence components as heatmaps and line plots.

Parameters:

adata (AnnData) -- AnnData object with CP decomposition in varm and uns.
output_dir (Path | str) -- Directory to write plots into.
components_key (str (default: 'H_cp_sequence')) -- Key in adata.varm for position factors.
uns_key (str (default: 'cp_sequence')) -- Key in adata.uns for CP metadata (base factors/labels).
base_factors_key (str | None (default: None)) -- Optional key in adata.uns for base factors.
suffix (str | None (default: None)) -- Optional suffix appended to the component keys.
heatmap_name (str (default: 'cp_sequence_position_heatmap.png')) -- Filename for the heatmap plot.
lineplot_name (str (default: 'cp_sequence_position_lineplot.png')) -- Filename for the line plot.
base_factors_name (str (default: 'cp_sequence_base_weights.png')) -- Filename for the base factors plot.
max_positions (int (default: 2000)) -- Maximum number of positions to plot.

Returns:

Paths to generated plots.

Return type:

Dict[str, Path]

smftools.plotting.general_plotting.plot_embedding(adata, *, basis, color, output_dir, prefix=None, point_size=12, alpha=0.8)#

Plot a 2D embedding with scanpy-style color options.

Parameters:

adata (AnnData) -- AnnData object with obsm['X_<basis>'].
basis (str) -- Embedding basis name (e.g., 'umap', 'pca').
color (Union[str, Sequence[str]]) -- Obs column name or list of names to color by.
output_dir (Path | str) -- Directory to save plots.
prefix (str | None (default: None)) -- Optional filename prefix.
point_size (float (default: 12)) -- Marker size for scatter plots.
alpha (float (default: 0.8)) -- Marker transparency.

Returns:

Mapping of color keys to saved plot paths.

Return type:

Dict[str, Path]

smftools.plotting.general_plotting.plot_embedding_grid(adata, *, basis, color, output_dir, prefix=None, ncols=None, point_size=12, alpha=0.8)#

Plot a 2D embedding grid with legends to the right of each subplot.

Parameters:

adata (AnnData) -- AnnData object with obsm['X_<basis>'].
basis (str) -- Embedding basis name (e.g., 'umap', 'pca').
color (Union[str, Sequence[str]]) -- Obs column name or list of names to color by.
output_dir (Path | str) -- Directory to save plots.
prefix (str | None (default: None)) -- Optional filename prefix.
ncols (int | None (default: None)) -- Number of columns in the grid.
point_size (float (default: 12)) -- Marker size for scatter plots.
alpha (float (default: 0.8)) -- Marker transparency.

Return type:

Path | None

Returns:

Path to the saved grid image, or None if no valid color keys exist.

smftools.plotting.general_plotting.plot_read_span_quality_clustermaps(adata, sample_col='Sample_Names', reference_col='Reference_strand', quality_layer='base_quality_scores', read_span_layer='read_span_mask', quality_cmap='viridis', read_span_color='#2ca25f', sort_method='hierarchical', pca_n_components=20, pca_sort_component=0, max_nan_fraction=None, min_quality=None, min_length=None, min_mapped_length_to_reference_length_ratio=None, demux_types=('single', 'double', 'already'), max_reads=None, xtick_step=None, xtick_rotation=90, xtick_fontsize=9, show_position_axis=False, position_axis_tick_target=25, save_path=None, n_jobs=1, index_col_suffix=None)#

Plot read-span mask and base quality clustermaps side by side.

Clustering is performed using the base-quality layer ordering, which is then applied to the read-span mask to keep the two panels aligned.

Parameters:

adata -- AnnData with read-span and base-quality layers.
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.
quality_layer (str (default: 'base_quality_scores')) -- Layer name containing base-quality scores.
read_span_layer (str (default: 'read_span_mask')) -- Layer name containing read-span masks.
quality_cmap (str (default: 'viridis')) -- Colormap for base-quality scores.
read_span_color (str (default: '#2ca25f')) -- Color for read-span mask (1-values); 0-values are white.
sort_method (str (default: 'hierarchical')) -- Row ordering strategy ("pca" or "hierarchical").
pca_n_components (int | None (default: 20)) -- Number of PCA components to compute for ordering. If None, uses min(n_reads, n_positions).
pca_sort_component (int (default: 0)) -- Zero-based PCA component index to sort by (ascending).
max_nan_fraction (float | None (default: None)) -- Optional maximum fraction of NaNs allowed per position; positions above this threshold are excluded.
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.
max_reads (int | None (default: None)) -- Optional maximum number of reads to plot per sample/reference.
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.
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.
save_path (str | Path | None (default: None)) -- Optional output directory for saving plots.
n_jobs (int (default: 1)) -- Number of parallel worker processes. -1 uses all available CPUs. Parallelism is only applied when save_path is set (interactive display is always serial).
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 dictionaries with per-plot metadata and output paths.

smftools.plotting.general_plotting.plot_pca(adata, *, subset=None, color, output_dir, prefix=None, point_size=12, alpha=0.8)#

Return type:: Dict[str, Path]

smftools.plotting.general_plotting.plot_pca_grid(adata, *, subset=None, color, output_dir, prefix=None, ncols=None, point_size=12, alpha=0.8)#

Return type:: Path | None

smftools.plotting.general_plotting.plot_pca_explained_variance(adata, *, subset=None, output_dir, pca_key='pca', suffix=None, max_pcs=None)#

Plot cumulative explained variance for PCA results.

Parameters:

adata (AnnData) -- AnnData object containing PCA results in uns.
subset (str | None (default: None)) -- Optional subset suffix used in key naming.
output_dir (Path | str) -- Directory to write the plot into.
pca_key (str (default: 'pca')) -- Base key in adata.uns storing PCA results.
suffix (str | None (default: None)) -- Optional suffix to append to the key.
max_pcs (int | None (default: None)) -- Optional cap on number of PCs to plot.

Return type:

Path | None

Returns:

Path to the saved plot, or None if explained variance is unavailable.

smftools.plotting.general_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.general_plotting.plot_umap(adata, *, subset=None, color, output_dir, prefix=None, point_size=12, alpha=0.8)#

Return type:: Dict[str, Path]

smftools.plotting.general_plotting.plot_umap_grid(adata, *, subset=None, color, output_dir, prefix=None, ncols=None, point_size=12, alpha=0.8)#

Return type:: Path | None

smftools.plotting.general_plotting

Contents

smftools.plotting.general_plotting#

Returns#

Parameters#

Returns#