smftools.analysis.plot.embeddings

embeddings.py — Scatter and density plots for 2D embeddings (PCA/UMAP).

Functions

plot_embedding_scatter Scatter plot of an embedding, coloured by a categorical column. plot_embedding_density_grid Grid of per-category 2D KDE density panels over a shared extent. plot_cluster_composition_barplot Stacked barplot of per-sample cluster proportions. plot_cluster_proportion_grouped_barplot Grouped barplot (cluster on x-axis, one bar per sample per cluster) with cell-type fill colours, WT/enh-del hatching, and per-biorep points overlaid. plot_explained_variance Scree plot of per-PC explained variance ratio with cumulative explained variance overlaid.

Functions

plot_cluster_composition_barplot(df, ...[, ...])	Stacked barplot of per-sample cluster composition.
plot_cluster_proportion_grouped_barplot(df, ...)	Single-axes grouped barplot of per-sample cluster proportions.
plot_embedding_density_grid(df, x_col, ...)	Grid of 2D KDE density panels, one per category in facet_col.
plot_embedding_scatter(df, x_col, y_col, ...)	Scatter plot of a 2D embedding (e.g. UMAP1 vs UMAP2), coloured by a categorical column.
plot_explained_variance(...[, n_pcs_show, ...])	Scree plot: bar chart of per-PC explained variance ratio, with cumulative explained variance overlaid on a secondary y-axis.

smftools.analysis.plot.embeddings.plot_embedding_scatter(df, x_col, y_col, color_col, output_path, color_map=None, color_labels=None, color_order=None, point_size=5.0, alpha=0.6, title='', xlabel=None, ylabel=None, figsize=(4.5, 4.0), dpi=300, marginal_density=False, marginal_grid_size=200, marginal_bw_method=None)

Scatter plot of a 2D embedding (e.g. UMAP1 vs UMAP2), coloured by a categorical column.

Return type:

None

Parameters

df : DataFrame containing x_col, y_col, color_col. color_map : category -> hex colour; missing categories auto-assigned from tab10. color_labels : category -> display label for the legend. color_order : explicit category order for plotting/legend (default: first appearance). marginal_density : if True, add 1D KDE marginal panels per category alongside the scatter.

smftools.analysis.plot.embeddings.plot_embedding_density_grid(df, x_col, y_col, facet_col, output_path, facet_order=None, facet_labels=None, grid_size=100, bw_method=None, n_cols=3, cmap='viridis', shared_scale=True, pad_frac=0.05, figsize_per_panel=(3.0, 2.6), dpi=300)

Grid of 2D KDE density panels, one per category in facet_col.

Each panel is a Gaussian KDE of (x_col, y_col) for that category, evaluated on a shared grid spanning the full df extent and renormalised so the discretised grid integrates to 1 (a probability density, comparable across panels regardless of category size).

Return type:

None

Parameters

facet_order : explicit category order (default: order of first appearance). facet_labels : category -> display label for panel titles. grid_size : number of grid points per axis. bw_method : passed to scipy.stats.gaussian_kde (None -> Scott's rule). shared_scale : use the same vmax (density colour scale) across all panels.

smftools.analysis.plot.embeddings.plot_cluster_composition_barplot(df, sample_col, cluster_col, output_path, sample_order=None, sample_labels=None, cluster_order=None, cluster_labels=None, cluster_colors=None, title='', bar_width_in=0.6, height_in=4.0, dpi=300)

Stacked barplot of per-sample cluster composition.

For each category in sample_col (one bar), shows the proportion of rows falling into each category of cluster_col, stacked to 1.0.

Return type:

None

Parameters

sample_order : explicit bar order (default: order of first appearance). cluster_order : explicit stacking order (default: sorted unique values). cluster_colors : cluster -> hex colour; unspecified clusters auto-assigned from tab10.

smftools.analysis.plot.embeddings.plot_cluster_proportion_grouped_barplot(df, sample_col, cluster_col, biorep_col, cell_type_col, output_path, sample_order=None, cluster_order=None, cluster_labels=None, cell_type_colors=None, cell_type_labels=None, color_overrides=None, color_override_labels=None, enh_del_keyword='enh-del', point_size=14.0, jitter=0.06, group_width=0.8, figsize=(9.5, 4.5), title='', dpi=300)

Single-axes grouped barplot of per-sample cluster proportions.

cluster_col categories form the x-axis; within each cluster, one bar per category in sample_col is drawn side by side. Bar fill colour is keyed off cell_type_col; bars whose sample_col value contains enh_del_keyword (case-insensitive) are drawn with a cross-hatch, all others solid. For each bar, the height is the mean across biorep_col of that biorep's proportion of reads in the cluster, with individual biorep proportions overlaid as jittered points. A legend maps cell-type colours and the solid/hatched (WT/enh-del) convention.

Return type:

None

Parameters

sample_order : explicit bar order within each cluster group (default: first appearance). cluster_order : explicit x-axis order (default: sorted unique values). cell_type_colors : cell type -> hex colour; unspecified types auto-assigned from tab10. cell_type_labels : cell type -> display label for the legend. color_overrides : sample -> hex colour, overriding cell_type_colors for that bar. color_override_labels : sample -> legend label, overriding cell_type_labels when colour is overridden.

smftools.analysis.plot.embeddings.plot_explained_variance(explained_variance_ratio, output_path, n_pcs_show=20, figsize=(6.0, 4.0), title='', dpi=300)

Scree plot: bar chart of per-PC explained variance ratio, with cumulative explained variance overlaid on a secondary y-axis.

Return type:

None

Parameters

explained_variance_rationp.ndarray

1D array from sklearn PCA.explained_variance_ratio_.

output_pathPath

PNG output path.

n_pcs_showint

number of leading PCs to plot.