qdiv.plot.heatmap

qdiv.plot.heatmap(obj, *, group_by=None, value_aggregation='sum', order=None, levels=None, include_index=False, levels_shown=None, subset_levels=None, subset_patterns=None, n=20, featurelist=None, method='max', sorting='abundance', use_values_in_tab=False, italics=False, figsize=(14, 10), fontsize=15, sep_col=None, sep_line=None, labels=True, labelsize=10, color_threshold=8.0, cmap='Reds', gamma=0.5, colorbar_ticks=None, vmin=None, vmax=None, dpi=240, savename=None)[source]

Plot a heatmap of taxa abundances.

Parameters:

  • obj (dict or MicrobiomeData) –

    Input data containing at least:
    • ’tab’: pandas.DataFrame

      Abundance table (features x samples).

    • ’tax’: pandas.DataFrame

      Taxonomy table (features x taxonomic levels).

  • group_by (str or list, optional) – Metadata column(s) used to merge samples.

  • value_aggregation ({'sum', 'mean'}, default = 'sum')

  • order (str, optional) – Metadata column used to order samples along the x-axis.

  • levels (list of str, optional) – Taxonomic levels used for y-axis grouping.

  • include_index (bool, default=False) – Whether to include the feature index in labels.

  • levels_shown ({'number', None}, optional) – If ‘number’, show numeric labels instead of taxonomic names.

  • subset_levels (str or list of str, optional) – Taxonomic levels to filter by.

  • subset_patterns (str or list of str, optional) – Text patterns to filter taxa.

  • n (int, default=20) – Number of top taxa to plot (ignored if featurelist is provided).

  • featurelist (list of str, optional) – Specific features to plot.

  • method ({'max', 'min'}, default = 'max')

  • sorting ({'abundance', 'alphabetical'}, default = 'abundance')

  • italics (bool, default=False) – If True, italicize taxonomic names where appropriate.

  • figsize (tuple of float, default=(14, 10)) – Figure size in inches.

  • fontsize (int, default=15) – Font size for axis labels.

  • sep_col (list of int, optional) – Column indices where separators are inserted.

  • sep_line (list of int, optional) – Column indices where vertical lines are drawn.

  • labels (bool, default=True) – Whether to show abundance values in cells.

  • labelsize (int, default=10) – Font size of cell labels.

  • color_threshold (float, default=8.0) – Threshold for switching label color (black/white).

  • cmap (str, default='Reds') – Colormap for heatmap.

  • gamma (float, default=0.5) – Gamma for PowerNorm scaling.

  • colorbar_ticks (list of float, optional) – Tick marks for colorbar.

  • vmin (float, optional) – Minimum value for cplor normalization (passed to PowerNorm).

  • vmax (float, optional) – Maximum value for cplor normalization (passed to PowerNorm).

  • dpi (int, default 240) – Resolution of saved figure.

  • savename (str, optional) – Filename to save figure (PNG and PDF). If None, figure is not saved.

  • use_values_in_tab (bool, default = False)

Returns:

  • fig (matplotlib.figure.Figure) – The created figure.

  • ax (matplotlib.axes.Axes) – The matplotlib Axes object for the figure.

  • table (pandas.DataFrame) – The final abundance table (after grouping, filtering, and sorting) that was plotted.

Return type:

Tuple[Figure, Axes, DataFrame]

Examples

>>> heatmap(obj, group_by='Treatment', levels=['Genus'], n=30, savename='heatmap.png')