scmidas.plot

scmidas.plot#

Plotting helpers for MIDAS / MuData users.

The high-level helpers (umap(), modality_grid()) take a MuData directly and route through a temporary AnnData wrapper, side-stepping the current limitations of scanpy + MuData plotting. They are exposed as both scmidas.plot.X and the shorter scmidas.pl.X.

The AnnData-only helpers plot_umap(), plot_umap_grid(), plot_z_umap_grid() are retained for backwards compatibility with older tutorial code.

scmidas.plot.modality_grid(model, mdata, *, batch_key: str = 'batch', label_key: str = 'label', figsize: float = 2.0, point_size: float = 2.0, fontsize: int = 10, transpose: bool = False, random_state: int = 42)[source]#

Per-modality vs per-batch UMAP grid (joint c plus single-modality c).

Internally runs model.predict(joint_latent=True, mod_latent=True), concatenates the per-modality biological latents, and tiles them as a (modality × batch) grid coloured by label_key. The grid view answers: “does each modality on its own carry enough signal to separate cell types in each batch?”

Parameters:

  • model – MIDAS A constructed (and trained or checkpoint-loaded) MIDAS model.

  • mdata – MuData The MuData passed to MIDAS(mdata).

  • batch_key – str Column in mdata.obs (or mdata[m].obs) identifying the batch.

  • label_key – str Column in mdata.obs (or mdata[m].obs) used for colouring.

  • figsize – float Per-subplot styling.

  • point_size – float Per-subplot styling.

  • fontsize – float Per-subplot styling.

  • transpose – bool If True, swap rows/columns (modality-by-batch instead of batch-by-modality).

  • random_state – int Seed used by sc.tl.umap.

Returns:

The aggregated AnnData used for the plot.

Return type:

AnnData

scmidas.plot.plot_umap(adata, key='z_c_joint', do_pca=False, n_comps=32, color='batch', shuffle=True, **kwargs)[source]#

Computes and plots a UMAP for a single AnnData object based on a specific latent representation.

This function allows for optional PCA preprocessing on the selected latent representation (stored in .obsm) before computing the neighborhood graph and UMAP.

Parameters:

  • adata (AnnData) – The input annotated data matrix.

  • key (str, optional) – The key in adata.obsm to use as the representation. Defaults to ‘z_c_joint’.

  • do_pca (bool, optional) – Whether to perform scaling and PCA on the representation before neighbor calculation. Defaults to False.

  • n_comps (int, optional) – The number of principal components to use if do_pca is True. Defaults to 32.

  • color (str, optional) – The key in adata.obs used to color the plot. Defaults to ‘batch’.

  • shuffle (bool, optional) – Shuffle the samples.

  • **kwargs – Additional keyword arguments passed to sc.pl.umap.

Returns:

Displays the plot.

Return type:

None

scmidas.plot.plot_umap_grid(adata, axis1, axis2, color, figsize=2, point_size=2, fontsize=10, background=True)[source]#

Plots a grid (facet plot) of UMAPs split by two categorical variables.

This visualizes how specific groups (defined by axis1 and axis2) are distributed within the global UMAP space.

Parameters:

  • adata (AnnData) – Annotated data matrix with pre-computed UMAP coordinates (X_umap).

  • axis1 (str) – Key in adata.obs defining the rows of the grid.

  • axis2 (str) – Key in adata.obs defining the columns of the grid.

  • color (str) – Key in adata.obs used for coloring the points.

  • figsize (float, optional) – The size (in inches) of each subplot. Defaults to 2.

  • point_size (float, optional) – The size of the scatter points. Defaults to 2.

  • fontsize (int, optional) – Font size for the legend. Defaults to 10.

  • background (bool, optional) – If True, plots all cells in grey in the background of each subplot to show the global structure. Defaults to True.

Returns:

Displays the plot.

Return type:

None

scmidas.plot.plot_z_umap_grid(adata_list, batch_col='batch', color='label', figsize=2, point_size=2, fontsize=10, transpose=False)[source]#

Aggregates latent representations from a dictionary of AnnData objects, computes a joint UMAP, and plots a grid view.

It specifically looks for keys in .obsm starting with ‘z_c’, concatenates them, and re-computes the UMAP to visualize the alignment or distribution across different batches/types.

Parameters:

  • adata_list (dict) – A dictionary where keys are batch identifiers and values are AnnData objects.

  • batch_col (str, optional) – Key in adata.obs identifying the batch/sample. Defaults to ‘batch’.

  • color (str, optional) – Key in adata.obs used for coloring. Defaults to ‘label’.

  • figsize (float, optional) – The size (in inches) of each subplot. Defaults to 2.

  • point_size (float, optional) – The size of the scatter points. Defaults to 2.

  • fontsize (int, optional) – Font size for the legend. Defaults to 10.

  • transpose (bool, optional) – If True, swaps the row and column axes of the grid (Batch vs. Type). Defaults to False.

Returns:

Displays the plot.

Return type:

None

scmidas.plot.umap(mdata, *, basis: str = 'X_midas', color: str | Sequence[str] = 'batch', obs_keys: Sequence[str] | None = None, n_neighbors: int = 30, min_dist: float = 0.3, random_state: int = 42, shuffle: bool = True, recompute: bool = False, **kwargs)[source]#

Compute and plot a UMAP from a MuData embedding (one-liner).

Wraps the MuData’s selected embedding as a thin AnnData and routes through sc.pl.umap, avoiding the current limitations of scanpy + MuData plotting.

Parameters:

  • mdata – MuData Multi-modal data with an integration embedding in mdata.obsm[basis] (e.g. written by get_latent_representation()).

  • basis – str Key in mdata.obsm to use as the representation. Default 'X_midas' matches MIDAS.get_latent_representation().

  • color – str or sequence of str One or more mdata.obs columns to color by. Mirrors scanpy’s color argument.

  • obs_keys – sequence of str, optional Which mdata.obs columns to copy onto the temporary AnnData. Defaults to the union of color plus any keys referenced by scanpy kwargs that read from .obs.

  • n_neighbors – Forwarded to sc.pp.neighbors / sc.tl.umap.

  • min_dist – Forwarded to sc.pp.neighbors / sc.tl.umap.

  • random_state – Forwarded to sc.pp.neighbors / sc.tl.umap.

  • shuffle – bool If True, shuffle cells before plotting (unbiased visual density when batches/cell types overlap).

  • recompute – bool If False (default) and mdata.obsm['X_umap_<basis>'] already exists, reuse it. If True, recompute UMAP.

  • **kwargs – Forwarded to sc.pl.umap.

Returns:

The temporary AnnData used for plotting (so callers can access .obsm['X_umap'] if they want to keep it).

Return type:

AnnData