Plot API

mutopia.plot.plot_component(dataset, component, *select, **kw)[source]

Plot a specific component from a dataset using its modality’s plotting method.

Parameters:

  • dataset (GTensorDataset) – Dataset containing signature components.

  • component (int or str) – Component index or identifier to plot.

  • *select (str, optional) – One or more state/section labels to plot (e.g., “Baseline”).

  • **kw (dict, optional) – Extra keyword arguments forwarded to the modality plot method.

Returns:

The axes containing the rendered plot.

Return type:

matplotlib.axes.Axes

mutopia.plot.plot_interaction_matrix(dataset, component, palette=<matplotlib.colors.LinearSegmentedColormap object>, gridspec=None, title=None, **kw)[source]

Generate a visualization of component interactions.

This method creates a plot showing the interaction matrix for a specified component. It displays shared effects and context-specific interactions for genomic signatures.

Parameters:

  • dataset (GTensorDataset) – Dataset containing the interactions to visualize.

  • component (int or str) – The component index or identifier to visualize.

  • palette (function, optional) – A color palette function to use for visualization, defaults to diverging_palette.

  • gridspec (matplotlib.gridspec.GridSpec, optional) – GridSpec to draw into; when None, a new Figure is created and used.

  • title (str, optional) – Label for the base-rate row.

  • **kw (dict) – Extra keyword arguments forwarded to the modality plot function.

Returns:

The sub-GridSpec used for the interaction plot layout.

Return type:

matplotlib.gridspec.GridSpec

Notes

The interaction matrix shows how the component behaves across different contexts, highlighting both shared effects and context-specific variations.

mutopia.plot.plot_shap_summary(data, source=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, figsize=(8, 5), scale=100, feature_order=None, component_order=None, ax=None, cbar=True, max_size=1000, linewidth=0.5, **scatter_kw)[source]
mutopia.plot.plot_signature_panel(dataset, *select, ncols=4, width=3.5, height=1.25, show=True, order=None, **kwargs)[source]

Create a panel of signature plots for all components in a dataset.

Parameters:

  • dataset (GTensorDataset) – Dataset containing signature components.

  • ncols (int, default=4) – Number of columns in the panel.

  • width (float, default=3.5) – Width of each subplot in inches.

  • height (float, default=1.25) – Height of each subplot in inches.

  • show (bool, default=True) – If True, display the figure; if False, return it.

  • **kwargs – Extra keyword arguments forwarded to plot_spectrum.

Returns:

The figure when show=False; otherwise None.

Return type:

matplotlib.figure.Figure or None

mutopia.plot.plot_signature_report(dataset, component, width=5.25, height=2.0, show=True, bubble_scale=300)[source]

Generate a comprehensive report for a specific signature component.

This method creates a figure with signature plots for mesoscale states and an interaction matrix for the specified component, providing a visual representation of the signature’s characteristics.

Parameters:

  • dataset (GTensorDataset) – Dataset containing the signature data.

  • component (int or str) – The signature component to visualize. Can be an integer index or a string identifier.

  • width (float, default=5.25) – The base width of the figure in inches. The actual figure width may be adjusted based on the number of states.

  • height (float, default=2.0) – The base height per signature group in inches.

  • show (bool, default=True) – Whether to display the figure immediately.

  • bubble_scale (float, default=300) – Scale parameter passed to the SHAP summary bubble sizes.

Returns:

The generated figure when show=False; otherwise None.

Return type:

matplotlib.figure.Figure or None

Notes

The report organizes mesoscale states into groups based on their prefix (before the colon), and displays them in separate rows. For singleton state groups (except Baseline), the Baseline state is automatically added as a reference.

mutopia.plot.plot_spectrum(signature, *select, **kw)[source]

Plot a component of a signature using its modality’s plotting method.

This wraps the modality-specific plot method. If no selection is provided, downstream modality implementations typically default to “Baseline”.

Parameters:

  • signature (xr.DataArray) – Signature data array to plot. Must implement signature.modality().plot(...).

  • *select (str, optional) – One or more state/section labels to plot (e.g., “Baseline”).

  • **kw (dict, optional) – Extra keyword arguments forwarded to the modality plot method.

Returns:

The axes containing the rendered plot.

Return type:

matplotlib.axes.Axes