cellspec.pl.spectrum

Contents

cellspec.pl.spectrum#

cellspec.pl.spectrum(adata, key='spectrum', cells=None, groupby=None, aggregate='sum', normalize=False, palette=None, outdir=None, figsize=(24, 6), dpi=600, title=None, ylabel=None, ylim=None, transparent=False)#

Plot mutation spectra for cells/samples or per-group private mutations.

Automatically detects whether spectrum is per-cell (adata.obsm) or per-group (adata.uns) and plots accordingly.

Parameters:

  • adata (ad.AnnData) – AnnData object with computed spectrum

  • key (str, default 'spectrum') – Key for spectrum in adata.obsm (per-cell) or adata.uns (per-group)

  • cells (list of str, optional) – Specific cells to plot. If None and groupby is None and aggregate is None, plots all cells as separate files. Note: Cannot be used with per-group spectra.

  • groupby (str, optional) – Column name from adata.obs to group by (e.g., ‘cell_type’, ‘sample_id’). If provided, plots one spectrum per group, aggregated by the method specified in ‘aggregate’. If None and aggregate is provided, aggregates across all cells. If None and aggregate is None, plots individual cells. Note: Cannot be used with per-group spectra (already grouped).

  • aggregate (str, default 'sum') – How to aggregate spectra: ‘sum’, ‘mean’, or None. - If groupby is provided: aggregates within each group - If groupby is None: aggregates across all cells - If None: plots individual cells (ignores groupby) Note: For per-group spectra, must be ‘sum’ or None.

  • normalize (bool, default False) – Normalize to proportions (sum to 1). For advanced normalization (by callable sites, coverage, etc.), use spc.tl.normalize_spectrum() first and plot the normalized key.

  • palette (str, list, dict, or None, optional) – Color palette for mutation types: - None or ‘default’: use default colors - ‘dark’: use dark-background compatible colors (C>G as light lavender) - list of 6 colors: colors for [‘C>A’, ‘C>G’, ‘C>T’, ‘T>A’, ‘T>C’, ‘T>G’] - dict: mapping mutation types to colors (e.g., {‘C>A’: ‘#00BCD4’, …})

  • outdir (str, optional) – Output directory for saving plots

  • figsize (tuple, default (24, 6)) – Figure size (per spectrum row)

  • dpi (int, default 600) – DPI for saved figures

  • title (str, optional) – Plot title (used for aggregate plots or individual cell prefix)

  • ylabel (str, optional) – Y-axis label. If None, uses “Mutation count” or “Proportion” based on normalize parameter

  • ylim (tuple of (float, float), optional) – Y-axis limits as (ymin, ymax). If None, automatically calculated from data.

  • transparent (bool, default False) – Save figure with transparent background (only affects saved files)

Return type:

None

Examples

>>> import cellspec as spc
>>> # Per-cell spectra examples:
>>> # Plot all cells as separate files
>>> spc.pl.spectrum(adata, key="somatic", outdir="figures/somatic/")

>>> # Plot aggregate spectrum (sum across all cells)
>>> spc.pl.spectrum(adata, key="somatic", aggregate="sum")

>>> # Plot aggregate spectrum (mean across all cells)
>>> spc.pl.spectrum(adata, key="somatic", aggregate="mean")

>>> # Plot spectra grouped by cell type (sum within each group)
>>> spc.pl.spectrum(adata, key="somatic", groupby="cell_type")

>>> # Plot spectra grouped by sample (mean within each group)
>>> spc.pl.spectrum(adata, key="somatic", groupby="sample_id", aggregate="mean")

>>> # Plot individual cells
>>> spc.pl.spectrum(adata, key="somatic", aggregate=None)

>>> # Plot specific cells
>>> spc.pl.spectrum(adata, key="somatic", cells=["cell_1", "cell_2", "cell_3"], aggregate=None)

>>> # Pre-normalize by callable sites then plot
>>> spc.tl.normalize_spectrum(
...     adata, key="somatic", method="obs_column", obs_column="callable_sites", output_key="somatic_rate"
... )
>>> spc.pl.spectrum(adata, key="somatic_rate", aggregate="sum")

>>> # Per-group spectra examples:
>>> # Compute and plot private mutation spectra per lineage
>>> spc.tl.private_mutations(adata, groupby="lineage", genotypes=[3], store_key="private")
>>> spc.tl.compute_spectrum(adata, genotypes=[3], private_key="private", key="private_spectra")
>>> spc.pl.spectrum(adata, key="private_spectra")  # Automatically detects per-group mode

Notes

Per-cell mode: - Spectrum stored in adata.obsm[f’spectrum_{key}’] - Shape: (cells × 96 contexts) - Supports groupby, aggregate, cells parameters

Per-group mode: - Spectrum stored in adata.uns[f’spectrum_{key}’] - Shape: (96 contexts × groups) - Already grouped/aggregated by private_mutations groups - Does not support groupby, cells parameters (raises error) - Automatically plots one row per group

For large datasets (>10 cells), using aggregate=’sum’ or groupby=’cell_type’ or saving individual files to outdir is recommended over plotting all cells in one figure.

For advanced normalization strategies (e.g., by callable sites, coverage, or custom vectors), use spc.tl.normalize_spectrum() before plotting.

Contents