pycea.pl.ancestral_linkage

pycea.pl.ancestral_linkage#

pycea.pl.ancestral_linkage(tdata, groupby=None, symmetrize=None, normalize=None, data=None, tree=None, cluster='average', cluster_mode=None, order=None, cmap=None, vmin=None, vmax=None, center=0, xticklabels=True, yticklabels=True, labelsize=None, cbar=True, ax=None, **kwargs)#

Plot ancestral linkage as a clustered heatmap.

Displays the category × category linkage computed by pycea.tl.ancestral_linkage() as a heatmap, with rows and columns ordered by hierarchical clustering. The matrix is rebuilt from the long-form statistics table so that symmetrize and normalize can be chosen independently of how pycea.tl.ancestral_linkage() was called.

Parameters:

  • tdata (TreeData) – The TreeData object.

  • groupby (str | None (default: None)) – The groupby / key_added used when running pycea.tl.ancestral_linkage(); statistics are read from tdata.uns[f"{groupby}_linkage_stats"]. If None, it is inferred from tdata.uns (requires exactly one *_linkage_stats entry).

  • symmetrize (Literal['mean', 'max', 'min', False, None] (default: None)) – How to symmetrize the directional (source → target) matrix before plotting: 'mean', 'max', 'min', or False to leave it asymmetric. If None (default), use the value recorded by pycea.tl.ancestral_linkage() in tdata.uns (defaults to False when it cannot be determined).

  • normalize (bool | None (default: None)) – If True, color by the enrichment value - permuted_value (centered at 0); if False, color by the raw linkage value. If None (default), use the value recorded by pycea.tl.ancestral_linkage() in tdata.uns (defaults to True when it cannot be determined).

  • data (DataFrame | None (default: None)) – Long-form statistics to plot. Uses tdata.uns[f"{groupby}_linkage_stats"] if None.

  • tree (str | None (default: None)) – If the statistics are per-tree (computed with by_tree=True), the tree to plot. If None, values are averaged across trees.

  • cluster (str | None (default: 'average')) – Linkage method (e.g. 'ward', 'average') used to order rows/columns by hierarchical clustering. If None, the categories are left in their original order. Ignored if order is given.

  • cluster_mode (Literal['similarity', 'dissimilarity', None] (default: None)) – Whether the matrix values are a 'similarity' (larger = more related, negated to a distance before clustering) or a 'dissimilarity' (larger = less related, used directly). If None (default), inferred from the recorded metric: 'dissimilarity' for metric='path' and 'similarity' otherwise.

  • order (Sequence[str] | None (default: None)) – Explicit order of categories (rows and columns). Overrides cluster.

  • cmap (str | None (default: None)) – Colormap for the heatmap. If None, defaults to 'RdBu_r' when normalize=True (diverging) and 'viridis' when normalize=False (sequential).

  • vmin (float | None (default: None)) – Lower / upper bounds of the color scale. If None, derived from the largest absolute off-diagonal deviation from center (diverging) or from the off-diagonal min / max (sequential).

  • vmax (float | None (default: None)) – Lower / upper bounds of the color scale. If None, derived from the largest absolute off-diagonal deviation from center (diverging) or from the off-diagonal min / max (sequential).

  • center (float | None (default: 0)) – The value at which to center the colormap. As with seaborn.heatmap(), this is only applied to the diverging (normalize=True) heatmap via TwoSlopeNorm; it is ignored for the sequential (normalize=False) heatmap. Set to None to disable centering.

  • xticklabels (bool (default: True)) – Whether to draw the column / row tick labels.

  • yticklabels (bool (default: True)) – Whether to draw the column / row tick labels.

  • labelsize (float | None (default: None)) – Font size for the tick labels.

  • cbar (bool (default: True)) – Whether to draw a colorbar.

  • ax (Axes | None (default: None)) – Axes on which to draw the plot. Creates new axes when None.

  • kwargs (Any) – Additional keyword arguments for pcolormesh().

Return type:

Axes

Returns:

ax - Axes containing the heatmap.