qdiv.plot.octave

qdiv.plot.octave(obj, *, group_by=None, values=None, nrows=2, ncols=2, fontsize=11, figsize=(10, 6), xlabels=True, ylabels=True, title=True, color='blue', savename=None)[source]

Plot octave distributions of ASV abundances according to Edgar & Flyvbjerg (DOI: 10.1101/38983).

This function bins feature counts into logarithmic intervals (powers of 2) and plots histograms for each sample or merged group of samples. Useful for visualizing abundance distributions across samples.

Parameters:

  • obj (dict or MicrobiomeData) –

    Input data containing at least:

    • ’tab’: pandas.DataFrame. Abundance table (features x samples).

    Optional key: - meta (pandas.DataFrame): metadata table for sample grouping.

  • group_by (str, optional) – Metadata column name used to merge samples by category. If None, each sample is plotted individually.

  • values (list of str, optional) – Subset of sample names or metadata values to include. If None, all samples or all categories in group_by are used.

  • nrows (int, default=2) – Number of rows in the subplot grid.

  • ncols (int, default=2) – Number of columns in the subplot grid. nrows * ncols must be >= number of panels.

  • fontsize (int, default=11) – Font size for plot text.

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

  • xlabels (bool, default=True) – Whether to show x-axis labels (k bins).

  • ylabels (bool, default=True) – Whether to show y-axis labels (ASV counts).

  • title (bool, default=True) – Whether to display sample name or group name as subplot title.

  • color (str, default='blue') – Color of the bars in the histograms.

  • savename (str, optional) – If provided, save the figure to this path and also as PDF. Additionally, export the bin counts as a CSV file (savename + '.csv').

Returns:

  • fig (matplotlib.figure.Figure)

  • df (pandas.DataFrame) – DataFrame containing bin definitions and counts per sample/group. Columns: [‘k’, ‘min_count’, ‘max_count’, sample1, sample2, …]. Returns None if plotting fails due to insufficient panels.

Return type:

Tuple[plt.figure.Figure, pd.DataFrame]

Notes

  • Bins are defined as intervals [2^k, 2^(k+1)).

  • If the number of samples exceeds nrows * ncols, the function prints a warning and returns None without plotting.

Examples

>>> df = octave(obj, group_by='Treatment', nrows=2, ncols=3, color='green', savename='octave_plot')
>>> print(df.head())