qdiv.plot.ordination

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