plot_graph_feature_heatmap

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_graph_feature_heatmap(table: pd.DataFrame, *, subjects: Sequence[str] | None = None, features: Sequence[str] | None = None, n_features: int = 40, feature_group: Literal['single', 'pair', 'all'] = 'single', select: Literal['variance', 'sample'] = 'variance', sample_seed: int = 0, zscore: bool = True, reference: 'pd.DataFrame' | None = None, star_significant: bool = False, star_alpha: float = 0.05, star_test: Literal['ttest_rel'] = 'ttest_rel', star_mtc: Literal['fdr_bh', 'bonferroni', 'none'] = 'fdr_bh', cbar_label: str | None = None, subject_col: str = 'subject_id', title: str | None = None, ax: Any | None = None) → Figure[source]

Draw a subject x graph-feature heatmap (not habitat x texture).

Columns in a graph table mix incompatible units (counts, ratios, path lengths). zscore=True (default) standardizes each selected feature across the selected subjects so a row is a relative profile, not a raw magnitude. Raw mixed units are not comparable; pass zscore=False only when every drawn column already shares one scale. Signed zscore=False values use a zero-centered diverging map.

For a lattice comparison (for example 5-voxel minus 8-voxel), pass the 5-voxel frame as table and the 8-voxel frame as reference. The function aligns subjects and shared feature columns, plots table - reference, and (when zscore=True) column-z-scores that raw difference. Do not pass a precomputed (or already z-scored) delta as table together with reference — that would subtract twice.

star_significant=True marks features (x-tick labels), not cells. Each plotted column gets a paired t-test (scipy.stats.ttest_rel of the two source tables; equivalent to a one-sample t of the raw difference against 0). Columns with fewer than 3 finite pairs or a constant difference are skipped. Multiple testing defaults to Benjamini-Hochberg FDR across the plotted features (scipy.stats.false_discovery_control, then statsmodels, then Bonferroni). Significant names get a trailing ASCII asterisk. Starring requires reference; a lone precomputed delta cannot reconstruct the pairing. Default star_significant=False so generic heatmaps stay unmarked.

Visualization parameters (who / which features / how many) are first-class: pass subjects and either an explicit features list or n_features + feature_group + select. The default cap is 40 columns so the full ~400-feature bank is never dumped onto one figure.

This is a different figure from plot_habitat_feature_heatmap() (habitats x radiomics features).

Parameters:

  • table – Wide frame, one row per subject. Identifier column defaults to subject_id. Domain FeatureTable frames use subject — pass subject_col='subject'. When reference is set this is the minuend (e.g. 5-voxel).

  • subjects – Subject ids to show, in y-axis order. None keeps every row. Missing ids raise HABITAPIError.

  • features – Exact column list. When set, it overrides n_features, select, and feature_group.

  • n_features – Column cap when features is omitted (default 40).

  • feature_group – 'single' (single_h*), 'pair' (pair_h*), or 'all' (those plus graph_num_*). graph_num_* is excluded from single / pair.

  • select – When features is omitted, take the top-k columns by cross-subject variance ('variance') or a reproducible random subset ('sample', seeded by sample_seed). With reference, variance is of the raw difference.

  • sample_seed – RNG seed for select='sample'.

  • zscore – Column-wise z-score across the selected subjects (default True). Requires at least two subjects. False draws the (possibly subtracted) values as-is.

  • reference – Optional paired frame (e.g. 8-voxel). When set, the plotted matrix is aligned table - reference. Required when star_significant=True.

  • star_significant – If True, append an ASCII asterisk to x-tick labels of features that stay significant after star_mtc. Default False; ignored pairing is never inferred from a precomputed delta alone.

  • star_alpha – Significance threshold after correction (default 0.05).

  • star_test – Paired test. Only 'ttest_rel' is supported.

  • star_mtc – Multiple-testing method over plotted features: 'fdr_bh' (default), 'bonferroni', or 'none'.

  • cbar_label – Optional colorbar label. None uses a default from the scale (Z-scored difference when reference and zscore are both set).

  • subject_col – Identifier column name (default 'subject_id').

  • title – Optional English figure title. None builds one from the group and whether values are z-scored.

  • ax – Optional existing axes. None creates a new figure.

Returns:

The matplotlib Figure. The caller decides whether to save it.

Raises:

  • HABITAPIError – Missing subjects / columns, empty selection, invalid knobs, star_significant=True without reference, or zscore=True with fewer than two rows.

  • OptionalDependencyError – When matplotlib is not installed.