qdiv.plot

plot

Provides plotting functions.

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')
qdiv.plot.rarefactioncurve(obj, distmat=None, *, step='flexible', div_type='naive', q=0.0, figsize=(14, 10), fontsize=18, color_by=None, order=None, tag=None, colorlist=None, only_return_data=False, only_plot_data=None, savename=None)[source]

Calculate and plot rarefaction curves for alpha diversity (Hill numbers).

The function subsamples (without replacement) individual reads within each sample to compute the rarefaction curve for a chosen diversity type, then plots per-sample curves. If only_return_data=True, it returns the computed curves instead of plotting them. You can also supply precomputed curves via only_plot_data to plot without recomputation.

Parameters:

  • obj (dict or MicrobiomeData) –

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

      Abundance table (features x samples).

    • meta (pd.DataFrame): metadata with sample IDs as index matching tab columns.

    Optional keys depending on div_type: - tree: phylogenetic tree object (required if div_type='phyl').

  • distmat (str or pandas.DataFrame or None, optional) – Distance matrix required when div_type='func'. Can be a preloaded DataFrame or a path-like string handled by your func_alpha implementation.

  • step ({'flexible'} or int, default='flexible') – Subsampling step size (depth increments). If ‘flexible’, the total reads of each sample are divided by 20 (min 1). If an integer, it must be a positive step size in reads.

  • div_type ({'naive', 'phyl', 'func'}, default='naive') – Diversity measure to compute: - ‘naive’ : taxonomic (plain) diversity via naive_alpha. - ‘phyl’ : phylogenetic diversity via phyl_alpha (requires tree). - ‘func’ : functional diversity via func_alpha (requires distmat).

  • q (float, default=0.0) – Order of diversity (Hill number).

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

  • fontsize (int, default=18) – Base font size for the plot.

  • color_by (str, optional) – Metadata column in used to color-code lines (group legend).

  • order (str, optional) – Metadata column in used to order samples along the legend or visual grouping in the plot.

  • tag ({'index'} or str, optional) – If ‘index’, annotate curve endpoints with sample IDs. If a metadata column name, annotate with that column’s values.

  • colorlist (list of str, optional) – Colors used for plotting. If not provided, colors are drawn from get_colors_markers('colors'). Ensure the list is long enough for all groups/samples.

  • only_return_data (bool, default=False) – If True, return the computed data dictionary and do not plot.

  • only_plot_data (dict, optional) – Precomputed data dictionary to plot (skips computation). The format is: {sample_id: (xvals: np.ndarray, yvals: np.ndarray)}.

  • savename (str, optional) – If provided, save the plot to savename and also to a PDF file savename + '.pdf' (unless savename already ends with .pdf).

Returns:

Returns a dictionary with the keys ‘meta’, which holds the metadata dataframe and ‘samples’, which is another dictionary mapping sample IDs to (x, y) arrays for the rarefaction curves.

Return type:

dict

Notes

  • The function shuffles individual reads per sample using numpy.random.shuffle. For reproducibility, set the global NumPy random seed before calling.

  • Helper functions naive_alpha, phyl_alpha, and func_alpha are assumed to be available in the current namespace.

  • The count table obj['tab'] must contain non-negative integers; zero-count features are ignored per sample during accumulation.

Examples

Compute and plot, coloring by a metadata column:

>>> data = rarefactioncurve(
...     obj,
...     step='flexible',
...     div_type='naive',
...     q=0,
...     color_by='Treatment',
...     savename='rarefaction.png'
... )

>>> rd = rarefactioncurve(obj, step=500, only_return_data=True)

Plot from precomputed data:

>>> _ = rarefactioncurve(obj, only_plot_data=rd)  # uses obj['meta'] for annotations
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())
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)[source]

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())
qdiv.plot.ordination(ordination_results=None, meta=None, *, color_by=None, shape_by=None, order=None, biplot=None, ellipse=None, title='', savename=None, show_legend=True, figsize=(9, 6), fontsize=12, markersize=50, markerscale=1.1, lw=1.0, pad=1.1, flipx=False, flipy=False, hide_ticks=False, connect=None, ellipse_connect=None, ellipse_std=2.0, tag=None, return_data=False, colors=None, markers=None, ellipse_colors=None, color_legend_marker=None, color_legend_title=None, shape_legend_title=None, which_axes=(0, 1), ax=None, legend_pos_colors=(1.0, 1.0), legend_pos_shapes=(1.0, 0.4))[source]

Create an ordination plot (PCoA or db-RDA) with optional grouping, biplots, and annotations.

Parameters:

  • ordination_results (pandas.DataFrame or dict) –

    • If a dissimilarity matrix (square DataFrame) is provided, stats.pcoa_lingoes will be run and a PCoA plotted.

    • If a results dict from stats.pcoa_lingoes or stats.dbrda is provided, those results will be plotted directly.

  • meta (DataFrame | MicrobiomeData-like | dict) – Metadata table with sample annotations.

  • color_by (str, optional) – Column in meta used to color points by group.

  • shape_by (str, optional) – Column in meta used to vary marker shapes by group.

  • order (str, optional) – Metadata column used to order samples for the color_by variable.

  • biplot (list of str, optional) – For PCoA: list of numeric metadata columns to display as biplot vectors. For db-RDA: set to None to use ‘biplot_scores’ from ordination results.

  • ellipse (str, optional) – Column in meta used to group samples for drawing confidence ellipses.

  • title (str, optional) – Plot title.

  • savename (str, optional) – Filename to save the figure. Extension determines format (e.g., .png, .pdf).

  • show_legend (bool, default=True) – Whether to display the legend.

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

  • fontsize (int, default=12) – Font size for labels and title.

  • markersize (float, default=50) – Size of scatter plot markers.

  • markerscale (float, default=1.1) – Scaling factor for legend markers.

  • lw (float, default=1.0) – Line width for ellipses and connections.

  • pad (float, default=1.1) – Padding factor for axis limits.

  • flipx (bool, default=False) – Flip the X-axis.

  • flipy (bool, default=False) – Flip the Y-axis.

  • hide_ticks (bool, default=False) – Hide axis ticks and labels.

  • connect (str, optional) – Column in meta to connect points in order (e.g., time series).

  • ellipse_connect (str, optional) – Column in meta to connect ellipse centers in order.

  • ellipse_std (float, default=2.0) – Number of standard deviations around the centroid that the ellipse is drawn.

  • tag (str, optional) – Column in meta or ‘index’ to annotate points.

  • return_data (bool, default=False) – If True, return processed plotting data instead of the figure.

  • colors (list of str, optional) – Custom list of colors for groups.

  • markers (list of str, optional) – Custom list of marker styles for groups.

  • ellipse_colors (list of str, optional) – Custom list of colors for ellipses.

  • color_legend_marker (str, default=None) – Shape of color legend marker. Defaults to a rectangular patch.

  • color_legend_title (str, optional) – Color legend title.

  • shape_legend_title (str, optional) – Marker legend title.

  • which_axes (tuple of int, default=(0, 1)) – Indices of ordination axes to plot.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw the plot on. If None, a new figure is created.

  • legend_pos_colors (tuple of float, default=(1, 1)) – Position of color legend. Only relevant for user-supplied ax.

  • legend_pos_shapes (tuple of float, default=(1, 0.4)) – Position of shape legend. Only relevant for user-supplied ax.

Returns:

  • fig (matplotlib.figure.Figure) – The matplotlib Figure object for the ordination.

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

  • meta (pandas.DataFrame) – meta data with ordination coordinates.

  • Uproj (pandas.DataFrame) – biplot coordinates (if used)

Return type:

Tuple[Figure, axes, DataFrame, DataFrame]

Notes

  • Supports both PCoA and db-RDA ordination results.

  • Ellipses represent group dispersion; biplots show variable contributions.

  • Axis flipping and padding allow fine control over plot appearance.

Examples

>>> fig = ordination(pcoa_results, meta, color_by='Treatment', ellipse='Group')
>>> fig.savefig('ordination_plot.png')
qdiv.plot.dissimilarity_contributions(obj, *, by=None, q=1.0, div_type='naive', index='local', n=20, levels=None, from_file=None, figsize=(7.086614173228346, 5.511811023622047), fontsize=10, savename=None)[source]

Plot contributions of taxa to observed dissimilarity within categories.

This function visualizes how individual taxa contribute to dissimilarity (e.g., Bray-Curtis or Hill-based) across sample groups defined by metadata.

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).

    • meta (pandas.DataFrame): metadata table.

  • by (str, optional) – Metadata column used to categorize samples. Dissimilarity is calculated within each category.

  • q (float, default=1.0) – Diversity order (Hill number).

  • div_type ({'naive', 'phyl'}, default='naive') – Diversity type: - ‘naive’: taxonomic dissimilarity. - ‘phyl’: phylogenetic dissimilarity.

  • index ({'local', 'regional'}, default='local') – Index type for dissimilarity calculation.

  • n (int, default=20) – Number of top taxa to include in the plot.

  • levels (list of str, optional) – Taxonomic levels to include in y-axis labels (e.g., [‘Genus’]).

  • from_file (str, optional) – Path to a CSV file with precomputed dissimilarity contributions. If None, contributions are computed from obj.

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

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

  • savename (str, optional) – If provided, save the figure to this path and also as PDF.

Returns:

  • fig (matplotlib.figure.Figure)

  • df (pandas.DataFrame) – DataFrame of contributions for plotted taxa and categories. Returns None if computation or plotting fails.

Return type:

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

Notes

  • If from_file is provided, the function reads contributions from that file.

  • If levels is provided and div_type=’naive’, taxonomy names are appended to feature IDs.

  • For phylogenetic diversity, node names or feature sets are used for labeling.

Examples

>>> df = dissimilarity_contributions(obj, by='Treatment', q=1, div_type='naive', levels=['Genus'])
>>> print(df.head())
qdiv.plot.phyl_tree(obj, *, width=12, name_internal_nodes=False, abundance_info=None, xlog=False, savename=None)[source]

Plot a phylogram from a tree DataFrame with optional abundance bars.

Parameters:

  • obj (dict or MicrobiomeData) – Input object with required key: - tree (pandas.DataFrame): tree structure with columns [‘nodes’, ‘leaves’, ‘branchL’]. Optional keys: - tab (pandas.DataFrame): abundance table (features x samples). - meta (pandas.DataFrame): metadata table for sample grouping.

  • width (float, default=12) – Width of the plot in centimeters. Height is set automatically based on number of ASVs.

  • name_internal_nodes (bool, default=False) – If True, labels are added to internal nodes.

  • abundance_info ({'index'} or str, optional) – If ‘index’, plot relative abundance bars for each ASV. If a metadata column name, plot grouped abundance bars for each category.

  • xlog (bool, default=False) – If True, abundance bars use a logarithmic x-axis.

  • savename (str, optional) – If provided, save the figure to this path and also as PDF.

Returns:

  • fig (matplotlib.figure.Figure)

  • df_endN (pandas.DataFrame) – DataFrame of end nodes with positions and optional abundance info.

Return type:

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

Notes

  • The tree DataFrame must contain columns: ‘nodes’, ‘leaves’, ‘branchL’.

  • If abundance_info is provided, relative abundances are computed per leaf or category.

  • Bars are plotted to the right of the tree when abundance_info is not None.

Examples

>>> phyl_tree(obj, width=15, name_internal_nodes=True, abundance_info='Treatment', xlog=True, savename='phylogram')
qdiv.plot.harvey_balls(meta, columns_by=None, *, rows_by='index', row_colors=None, column_colors=None, row_label_width=4, figsize=(7.086614173228346, 5.511811023622047), fontsize=10, savename=None)[source]

Plot Harvey balls (fraction-of-circle indicators) for percentage columns in metadata.

Parameters:

  • meta (DataFrame | MicrobiomeData-like | dict) – Object with metadata table. Must contain the columns_by fields and optionally a rows_by field used to derive row labels.

  • columns_by (list of str) – List of metadata column names containing percentages (0–100) to visualize as Harvey balls across rows.

  • rows_by (str, default='index') – Name of the metadata column used as row labels. If ‘index’, the DataFrame index is used as row labels.

  • row_colors (str, optional) – Name of metadata column containing per-row text colors (e.g., ‘red’, ‘#333’). If None, all row labels are drawn in black.

  • column_colors (list of str, optional) – Colors for the column headers (one per columns_by). If None, defaults to black for all headers; if provided but shorter than columns_by, the list is padded with black.

  • row_label_width (int, default=4) – Number of GridSpec columns reserved for the row label area (left-hand text).

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

  • fontsize (int, default=10) – Base font size for the figure.

  • savename (str, optional) – If provided, saves the figure (PNG) to this path and also as PDF (savename + ‘.pdf’).

Returns:

  • fig (matplotlib.figure.Figure)

  • plot_data (pandas.DataFrame) – A DataFrame containing the row labels and selected percentage values used for plotting: columns [‘__label__’, *columns_by]. Returns None if validation fails.

Return type:

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

Notes

  • Harvey balls are drawn using pie charts where the black wedge represents the percentage, and the white wedge represents the complement to 100%.

  • All values in columns_by must be numeric (0–100). Non-numeric rows are coerced if possible; rows with missing values will still be plotted (missing values treated as 0).

  • If rows_by=’index’, row labels are taken from meta.index; otherwise, from meta[rows_by].

Examples

>>> df = harvey_balls(
...     meta,
...     rows_by='Treatment',
...     columns_by=['PFAS_%', 'DOC_%'],
...     row_colors='TreatmentColor',
...     column_colors=['#1f77b4', '#ff7f0e'],
...     savename='harvey_balls'
... )
>>> print(df.head())
qdiv.plot.alpha_diversity_profile(obj, *, q_range=(0.0, 2.0), q_step=0.05, distmat=None, div_type='naive', color_by=None, order=None, ylog=False, figsize=(7.086614173228346, 5.511811023622047), fontsize=10, colorlist=None, use_values_in_tab=False, savename=None)[source]

Plot alpha diversity vs diversity order across samples.

This function computes alpha diversity (Hill numbers) for a range of diversity orders q and plots the curves per sample. It supports taxonomic, phylogenetic, and functional diversity depending on div_type.

Parameters:

  • obj (dict or MicrobiomeData) –

    Input data structure containing at least:

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

    • meta (pandas.DataFrame): sample metadata.

    If div_type=’phyl’, must also contain:

    • tree (pandas.DataFrame or compatible structure): phylogenetic tree info.

  • q_range (tuple of float, default=(0.0, 2.0)) – Inclusive range (start, end) of diversity orders to evaluate.

  • q_step (float, default=0.05) – Step size between q values. Must be positive.

  • distmat (pandas.DataFrame, optional) – Functional distance matrix (features x features). Required when div_type=’func’.

  • div_type ({'naive', 'phyl', 'func'}, default='naive') – Diversity type: - ‘naive’: taxonomic alpha diversity. - ‘phyl’ : phylogenetic alpha diversity (requires tree in obj). - ‘func’ : functional alpha diversity (requires distmat).

  • color_by (str, optional) – Metadata column name used to group legend colors. If None, each sample is labeled individually.

  • order (str, optional) – Metadata column name used to sort samples before plotting.

  • ylog (bool, default=False) – If True, plot alpha diversity on a logarithmic y-scale.

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

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

  • colorlist (list of str, optional) – List of colors to use for groups or samples. If None, uses package defaults via get_colors_markers('colors') or Matplotlib’s cycle.

  • use_values_in_tab (bool, default=False) – Pass-through flag to alpha diversity backends (e.g., whether tab is already normalized).

  • savename (str, optional) – If provided, saves the figure to this path and also as PDF (i.e., savename and savename + ‘.pdf’).

Returns:

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

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

  • df (pandas.DataFrame) – DataFrame with rows = q-values and columns = samples, containing computed alpha diversity values.

Return type:

Tuple[Figure, Axes, DataFrame]

Notes

  • For div_type=’phyl’, get_df(obj, ‘tree’) must exist.

  • For div_type=’func’, distmat must be provided and compatible with tab.

  • The legend groups are deduplicated using the values of color_by. Only the first occurrence of each group is shown in the legend.

Examples

>>> fig, ax, df = alpha_diversity(obj, q_range=(0, 2), q_step=0.1,
...                           div_type='naive', color_by='Treatment')
>>> df.head()
qdiv.plot.beta_diversity_profile(obj, *, q_range=(0.0, 2.0), q_step=0.05, distmat=None, group_by=None, order=None, dis=True, viewpoint='regional', div_type='naive', ylog=False, figsize=(7.086614173228346, 5.511811023622047), fontsize=10, colorlist=None, savename=None, drop_na_groups=True)[source]

Plot multi-sample β-diversity (or its dissimilarity transform) vs diversity order q.

This function evaluates β_q across a grid of q-values using naive_multi_beta and plots a curve per group (or a single curve labeled ‘all’ if group_by=None). It can optionally convert β to dissimilarity using the “local” or “regional” viewpoints (as returned by naive_multi_beta).

Parameters:

  • obj (dict or MicrobiomeData-like) – Must support get_df(obj, ‘tab’) -> DataFrame (features × samples) and get_df(obj, ‘meta’) -> DataFrame (sample metadata).

  • q_range ((float, float), default=(0.0, 2.0)) – Inclusive (start, end) range of q-values.

  • q_step (float, default=0.05) – Step size between consecutive q values. Must be positive.

  • distmat (pandas.DataFrame, optional) – Functional distance matrix (features x features). Required when div_type=’func’.

  • group_by (str or None, default=None) – Metadata column defining groups of samples. If None, treats all samples as one group.

  • order (str or None, default=None) – Metadata column used to sort samples before computing group order. The order of first appearance of groups in the (optionally) sorted metadata determines the plotting order.

  • dis (bool, default=True) – If True, plot dissimilarity instead of raw β. Uses the viewpoint column (‘local_dis’ or ‘regional_dis’) returned by naive_multi_beta.

  • viewpoint ({'local', 'regional'}, default='regional') – Which dissimilarity column to use when dis=True.

  • div_type ({'naive', 'phyl', 'func'}, default='naive') – Diversity type: - ‘naive’: taxonomic alpha diversity. - ‘phyl’ : phylogenetic alpha diversity (requires tree in obj). - ‘func’ : functional alpha diversity (requires distmat).

  • ylog (bool, default=False) – If True, use a logarithmic y-scale. Note that dissimilarities may include zeros, which cannot be shown on a log scale; such points will be omitted.

  • figsize ((float, float), default=(18/2.54, 14/2.54)) – Figure size in inches.

  • fontsize (int, default=10) – Base font size.

  • colorlist (list of str or None, default=None) – Colors for groups. If None, uses Matplotlib’s default color cycle.

  • savename (str or None, default=None) – If provided, saves the figure as savename (raster) and savename + ‘.pdf’.

  • drop_na_groups (bool, default=True) – If True, drops groups that are entirely NaN across all q (e.g., groups with <2 samples).

Returns:

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

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

  • df (pandas.DataFrame) – DataFrame with rows = q-values and columns = groups. Contains β (if dis=False) or dissimilarity (if dis=True) for each group at each q.

Return type:

Tuple[Figure, Axes, DataFrame]

qdiv.plot.phylo_tree(tree, *, ax=None, label_tips=True, label_internals=False, tip_order='as_is', leaf_prefix='in', linewidth=1.5, color='k', figsize=None, fontsize=10, ladderize=True, scale_bar=None, savename=None)[source]

Plot a rooted phylogenetic tree as a rectangular phylogram.

This function renders a rooted phylogenetic tree using branch lengths as horizontal distances (rectangular layout) and returns the Matplotlib Axes object. Tip (leaf) positions are laid out vertically, and internal node positions are computed as the mean of their descendant tips.

Parameters:

  • tree (MicrobiomeData, dict, or compatible object) – Input data. Must contain a ‘tree’ dataframe

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw the tree on. If None, a new figure and axes are created.

  • label_tips (bool, default True) – If True, label leaf (tip) nodes with their node names.

  • label_internals (bool, default False) – If True, label internal nodes with their node names.

  • tip_order ({"as_is", "alpha"}, default "as_is") –

    Ordering of tips along the y-axis. - "as_is" preserves planar depth-first order from the root

    (respecting child order in the tree).

    • "alpha" orders tips alphabetically by node name.

  • leaf_prefix (str, default "in") – Prefix intended for leaf naming. Currently not used for filtering or labeling logic, but reserved for future extensions.

  • linewidth (float, default 1.5) – Line width used when drawing branches.

  • color (str or matplotlib-compatible color, default "k") – Color used for branches and labels.

  • figsize (tuple of float, optional) – Figure size (width, height) in inches when creating a new figure. If None, the height is scaled automatically based on the number of tips.

  • fontsize (int, default 10) – Font size used for tip and internal node labels.

  • ladderize (bool, default True) – If True, reorder child subtrees to produce a ladderized tree layout before plotting.

  • scale_bar (float, optional) – Length of the scale bar to draw (in branch-length units). If None, a scale bar corresponding to 10% of the tree width is drawn.

  • savename (str, optional) – If provided, save the figure to this file path using bbox_inches="tight".

Returns:

The Matplotlib Axes containing the plotted phylogenetic tree.

Return type:

matplotlib.axes.Axes

Raises:

  • ValueError – If the tree DataFrame is missing, malformed, or does not contain exactly one root.

  • RuntimeError – If y-positions for internal nodes cannot be resolved, indicating an invalid or cyclic tree structure.

Notes

  • Axis spines, ticks, and labels are removed for a clean tree layout.