cellspec.pl.compare_spectra

cellspec.pl.compare_spectra#

cellspec.pl.compare_spectra(adata, keys, aggregate='sum', normalize=False, palette=None, outpath=None, figsize=None, dpi=600, title=None, ylabel=None, ylim=None, transparent=False)#

Compare multiple spectra (e.g., different filtering strategies or conditions).

Supports both per-cell and per-group spectra. Per-group spectra are already aggregated, so each group will appear as a separate row in the plot.

Parameters:

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

  • keys (list of str) – Keys for spectra (in adata.obsm for per-cell or adata.uns for per-group)

  • aggregate (str, default 'sum') – How to aggregate each per-cell spectrum: ‘sum’ or ‘mean’. For per-group spectra, must be ‘sum’ (already aggregated).

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

  • palette (str, list, dict, or None, optional) – Color palette (see spc.pl.spectrum for details)

  • outpath (str, optional) – Path to save figure

  • figsize (tuple, optional) – Figure size. If None, auto-calculated based on number of spectra

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

  • title (str, optional) – Overall plot title (displayed at the top)

  • 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
>>> # Compare germline vs somatic (per-cell spectra)
>>> spc.pl.compare_spectra(
...     adata,
...     keys=["germline", "somatic"],
...     aggregate="sum",
...     normalize=True,
...     title="Germline vs Somatic",
...     outpath="figures/comparison.png",
... )
>>>
>>> # Compare with rate normalization
>>> spc.tl.normalize_spectrum(
...     adata, key="germline", method="obs_column", obs_column="callable_sites", output_key="germline_rate"
... )
>>> spc.tl.normalize_spectrum(
...     adata, key="somatic", method="obs_column", obs_column="callable_sites", output_key="somatic_rate"
... )
>>> spc.pl.compare_spectra(
...     adata,
...     keys=["germline_rate", "somatic_rate"],
...     aggregate="sum",
...     title="Germline vs Somatic (per callable site)",
... )
>>>
>>> # Compare per-group private mutation spectra
>>> # If 'private_spectra' has 3 groups, this will show all 3 in one plot
>>> spc.pl.compare_spectra(adata, keys=["private_spectra"], title="Private Mutations by Lineage")