smftools.plotting.latent_plotting

smftools.plotting.latent_plotting#

Functions

plot_cp_sequence_components(adata, *, output_dir)

Plot CP sequence components as heatmaps and line plots.

plot_embedding(adata, *, basis, color, ...)

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

plot_embedding_grid(adata, *, basis, color, ...)

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

plot_nmf_components(adata, *, output_dir[, ...])

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

plot_pca(adata, *[, subset, prefix, ...])

plot_pca_components(adata, *, output_dir[, ...])

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

plot_pca_explained_variance(adata, *[, ...])

Plot cumulative explained variance for PCA results.

plot_pca_grid(adata, *[, subset, prefix, ...])

plot_umap(adata, *[, subset, prefix, ...])

plot_umap_grid(adata, *[, subset, prefix, ...])

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

Dict[str, Path]

smftools.plotting.latent_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.latent_plotting.plot_pca(adata, *, subset=None, color, output_dir, prefix=None, point_size=12, alpha=0.8)#
Return type:

Dict[str, Path]

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