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]

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

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.