plot_msi_matrix

Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

plot_msi_matrix(matrix: np.ndarray, *, habitat_ids: Sequence[int] | None = None, title: str | None = None, scale: str = 'linear', mask_diagonal: bool | None = None, colorbar: ColorbarSpec = True) → Figure[source]

Heatmap of a spatial interaction (MSI) matrix.

Row/column 0 is background. Diagonal entries are connected-subregion size (M[0, 0] is background–background pairs in the padded bbox and is not exported as an MSI feature). Off-diagonal entries are interface counts. A shared linear colour scale over the full matrix is dominated by the diagonal, so the default scale='linear' masks the diagonal and stretches colour over the 2nd–98th percentiles of finite off-diagonal cells. The colorbar shows those same numeric limits. log1p is opt-in: on a nearly-constant off-diagonal block it flattens contrast further.

Parameters:

  • matrix – Square 2D array (row/column 0 is typically background).

  • habitat_ids – Optional labels for axes 1..K (background stays BG).

  • title – Optional figure title.

  • scale – "linear" (default), "normalized", "raw", or "log1p". "normalized" is \(P=M/D\) with the same \(D\) as habit.kernels.habitat_metrics.msi_features_from_matrix().

  • mask_diagonal – Mask the main diagonal in the colour scale. Default is True for linear / log1p / normalized, False for raw (full-matrix linear stretch).

  • colorbar – Draw a short vertical colorbar (default True). Pass False to hide it, or a mapping of style kwargs (shrink, pad, fraction, aspect, ticks, label, …) to override the default.

Returns:

A matplotlib Figure.

Examples using habit.viz.plot_msi_matrix

Quickstart: Python API

Quickstart: Python API