Base ModeConfig

The abstract base class for modality configuration. Concrete modes like SBS inherit from this to provide coordinates, ingestion, and plotting helpers.

class mutopia.modalities.mode_config.ModeConfig[source]

Bases: ABC

Abstract base class for modality configuration.

A ModeConfig defines the coordinate system, default palettes and labels, and a small set of utilities used by modality-specific models:

  • dimension/coordinate descriptions (coords, sizes, dims)

  • access to the modality-specific TopographyModel (TopographyModel)

  • helpers to load reference components and compute context frequencies

  • validation and plotting helpers for signatures/observations

Subclasses must implement coords, TopographyModel and the data pipeline methods get_context_frequencies and ingest_observations.

MODE_ID

Stable modality identifier string (e.g., “sbs”).

Type:

str

PALETTE

Default palette for plotting signatures for this modality.

Type:

list

X_LABELS

Optional x-axis labels to use when plotting (defaults to context labels).

Type:

list[str]

DATABASE

Relative path to a JSON file with named reference components.

Type:

str

DATABASE = None
MODE_ID = None
PALETTE = None
abstract property TopographyModel

Modality-specific TopographyModel class.

Implementations may import lazily to avoid cycles.

X_LABELS = None
property available_components

List available reference components in DATABASE.

Returns:

Names of components available for load_components.

Return type:

list[str]

component_spectra(source, normalization='none')[source]

Per-component reference spectra, from a fitted model or a gTensor.

Parameters:

  • source (TopographyModel or gTensor Dataset) – A fitted model — spectra are read straight off its context model, so no dataset is needed — or a dataset already annotated with Spectra/spectra by model.annot_components.

  • normalization ({"global", "weighted", "none"}, default="none") – "none" gives a per-context mutation rate, which is the convention the bundled signature database uses (see match_components()). "global" weights by the context distribution, giving a COSMIC-style probability over the 96 channels.

Returns:

  • xarray.DataArray with dims (component, context). Modalities whose

  • spectra carry extra state (SBS mesoscale genome_state) return the

  • baseline state, which is the one comparable to a reference database.

abstract property coords

Coordinate spec for this modality.

Returns:

Mapping from key to a pair of (dimension name, labels).

Return type:

dict[str, tuple[str, list]]

property dims

Tuple of dimension keys in the canonical order.

Returns:

Dimension keys corresponding to coords order.

Return type:

tuple[str, …]

abstractmethod classmethod get_context_frequencies(*, regions_file, fasta_file)[source]

Compute per-locus context frequencies for this modality.

Implementations must return an array with (configuration, context, locus) or analogous dims appropriate for the modality, using dense or sparse storage as needed.

abstractmethod classmethod ingest_observations(*, input_file, regions_file, fasta_file, **kwargs)[source]

Ingest raw input into a canonical observation tensor.

Implementations should return an xarray.DataArray with dims (configuration, context, mutation, locus) using dense or sparse storage. The array should include a name attribute identifying the sample.

load_components(*init_components)[source]

Load named reference components from the modality database.

Parameters:

*init_components (str) – Component names to load (must exist in available_components).

Returns:

Array of shape (component, context) with component spectra and modality metadata attached via attributes.

Return type:

xarray.DataArray

match_components(source, *reference, top_k=3, normalization='none')[source]

Match component spectra against the modality’s reference database.

Cosine similarity between each component’s spectrum and each reference signature. This is a spectrum comparison and says nothing about where a component sits in the genome — pair it with mutopia.analysis.TopographyUMAP for the topographic half.

Both sides are compared as per-context mutation rates, with the trinucleotide composition of the genome divided out. That is the convention the bundled database uses: its SBS1 places 98% of its mass on N[C>T]G, and only after multiplying by the genome’s trinucleotide frequencies does it return to COSMIC’s published ~87%. Published COSMIC profiles are genome-specific precisely because they bake that composition in; comparing a model rate against such a profile directly would systematically favour signatures concentrated in common contexts. Hence the normalization="none" default — do not change it to "global" without converting the database to match.

Parameters:

  • source (TopographyModel or gTensor Dataset)

  • *reference (str) – Reference signature names to compare against. Defaults to the whole database (available_components).

  • top_k (int, default=3) – Matches to report per component.

Returns:

Long form: component, rank, reference, cosine_similarity.

Return type:

pandas.DataFrame

Examples

>>> import mutopia.analysis as mu
>>> model = mu.load_model("cohort.model.pkl")
>>> mu.modalities.SBS.match_components(model, top_k=1)
>>> mu.modalities.SBS.match_components(model, "SBS4", "SBS6", top_k=2)
classmethod plot(signature, *select, palette=['#427aa1ff', '#e07a5fff', '#acacacff', '#83c5beff'], sig_names=None, normalize=False, title=None, width=5.25, height=1.25, ax=None, label_xaxis=True, **kwargs)[source]

Plot one or more modality signatures as a linear bar plot.

Parameters:

  • signature (xarray.DataArray) – Signature tensor with a trailing context dimension. May have an optional leading dimension to represent multiple signatures.

  • *select (str) – Optional names to select a subset of signatures from the leading dimension. Matching is exact or by name:prefix before the last colon.

  • palette (sequence, optional) – Color palette for plotting multiple signatures; defaults to the modality palette when a single signature is plotted.

  • sig_names (Sequence[str], optional) – Custom names for the selected signatures; must match selection size.

  • normalize (bool, default False) – If True, normalize each signature to sum to 1 before plotting.

  • title (str, optional) – Axes title.

  • width (float, default (5.25, 1.25)) – Figure sizing passed to the underlying plotting helper.

  • height (float, default (5.25, 1.25)) – Figure sizing passed to the underlying plotting helper.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on; if None, a new figure/axes is created.

  • label_xaxis (bool, default True) – Whether to show x-axis tick labels.

  • **kwargs – Additional keyword arguments forwarded to the plotting helper.

Returns:

The axes containing the rendered plot.

Return type:

matplotlib.axes.Axes

property sizes

Sizes of each coordinate dimension for this modality.

Returns:

Mapping from dimension key to number of labels.

Return type:

dict[str, int]

classmethod validate_observations(locus_dim, observations)[source]

Validate the observation tensor shape and required metadata.

Ensures dims match (configuration, context, mutation, locus) and that a name attribute is present.

classmethod validate_signatures(signature, required_dims=())[source]

Validate signature tensor structure for plotting or analysis.

Parameters:

  • signature (xarray.DataArray) – Signature tensor.

  • required_dims (Sequence[str]) – Required dimension names.