qdiv.plot.pie

qdiv.plot.pie(obj, *, group_by=None, value_aggregation='sum', order=None, levels=None, include_index=False, levels_shown=None, subset_levels=None, subset_patterns=None, n=6, featurelist=None, method='max', sorting='abundance', use_values_in_tab=False, nrows=1, ncols=1, figsize=(7.086614173228346, 3.937007874015748), fontsize=10, colorlist=None, other_color='grey', legend_columns=1, show_legend=True, savename=None)

Plot pie charts of taxonomic composition for samples or merged groups.

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, optional) – Metadata column 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 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')

• use_values_in_tab (bool)

• nrows (int)

• ncols (int)

• figsize (Tuple[float, float])

• fontsize (int)

• colorlist (List[str] | None)

• other_color (str)

• legend_columns (int)

• show_legend (bool)

• savename (str | None)

Return type:

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

nrowsint, default=1

Number of rows in the subplot grid.

ncolsint, default=1

Number of columns in the subplot grid.

figsizetuple of float, default=(18/2.54, 10/2.54)

Figure size in inches.

fontsizeint, default=10

Font size for titles and legend.

colorlistlist of str, optional

Colors for taxa slices. If None, defaults from get_colors_markers(‘colors’) are used.

other_color : Color for ‘Other’ slice. legend_columns : Number of columns in the legend. show_legend : Default is True.

Returns:

• fig (matplotlib.figure.Figure)

• table (pandas.DataFrame) – DataFrame of relative abundances for plotted taxa and samples. Returns None if required keys are missing.

Parameters:

• obj (Dict[str, Any] | Any)

• group_by (str | None)

• value_aggregation (Literal['sum', 'mean'])

• order (str | None)

• levels (List[str] | None)

• include_index (bool)

• levels_shown (str | None)

• subset_levels (str | List[str] | None)

• subset_patterns (str | List[str] | None)

• n (int)

• featurelist (List[str] | None)

• method (Literal['max', 'mean'])

• sorting (Literal['abundance', 'alphabetical'])

• use_values_in_tab (bool)

• nrows (int)

• ncols (int)

• figsize (Tuple[float, float])

• fontsize (int)

• colorlist (List[str] | None)

• other_color (str)

• legend_columns (int)

• show_legend (bool)

• savename (str | None)

Return type:

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

Notes

• Taxa are grouped by the specified level using groupbytaxa.

• Remaining taxa beyond n are aggregated into ‘Other’.

• If order is provided, samples are sorted by that metadata column.

Examples

>>> df = pie(obj, group_by='Treatment', level='Genus', n=8, savename='pie_chart')
>>> print(df.head())