qdiv.plot.ordination_plots module

class qdiv.plot.ordination_plots.Patch(*, edgecolor=None, facecolor=None, color=None, linewidth=None, linestyle=None, antialiased=None, hatch=None, fill=True, capstyle=None, joinstyle=None, hatchcolor=None, edgegapcolor=None, **kwargs)

Bases: Artist

A patch is a 2D artist with a face color and an edge color.

If any of edgecolor, facecolor, linewidth, or antialiased are None, they default to their rc params setting.

The following kwarg properties are supported

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: unknown animated: bool antialiased or aa: bool or None capstyle: .CapStyle or {‘butt’, ‘projecting’, ‘round’} clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None color: :mpltype:`color` edgecolor or ec: :mpltype:`color` or None edgegapcolor: :mpltype:`color` or None facecolor or fc: :mpltype:`color` or None figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure fill: bool gid: str hatch: {‘/’, ‘\’, ‘|’, ‘-’, ‘+’, ‘x’, ‘o’, ‘O’, ‘.’, ‘*’} hatch_linewidth: unknown hatchcolor: :mpltype:`color` or ‘edge’ or None in_layout: bool joinstyle: .JoinStyle or {‘miter’, ‘round’, ‘bevel’} label: object linestyle or ls: {‘-’, ‘–’, ‘-.’, ‘:’, ‘’, …} or (offset, on-off-seq) linewidth or lw: float or None mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

get_verts()

Return a copy of the vertices used in this patch.

If the patch contains Bézier curves, the curves will be interpolated by line segments. To access the curves as curves, use get_path.

contains(mouseevent, radius=None)

Test whether the mouse event occurred in the patch.

Parameters:

• mouseevent (~matplotlib.backend_bases.MouseEvent) – Where the user clicked.

• radius (float, optional) –

  Additional margin on the patch in target coordinates of .Patch.get_transform. See .Path.contains_point for further details.

  If None, the default value depends on the state of the object:

  • If .Artist.get_picker is a number, the default is that value. This is so that picking works as expected.

  • Otherwise if the edge color has a non-zero alpha, the default is half of the linewidth. This is so that all the colored pixels are “in” the patch.

  • Finally, if the edge has 0 alpha, the default is 0. This is so that patches without a stroked edge do not have points outside of the filled region report as “in” due to an invisible edge.

Return type:

(bool, empty dict)

contains_point(point, radius=None)

Return whether the given point is inside the patch.

Parameters:

• point ((float, float)) – The point (x, y) to check, in target coordinates of .Patch.get_transform(). These are display coordinates for patches that are added to a figure or Axes.

• radius (float, optional) –

  Additional margin on the patch in target coordinates of .Patch.get_transform. See .Path.contains_point for further details.

  If None, the default value depends on the state of the object:

  • If .Artist.get_picker is a number, the default is that value. This is so that picking works as expected.

  • Otherwise if the edge color has a non-zero alpha, the default is half of the linewidth. This is so that all the colored pixels are “in” the patch.

  • Finally, if the edge has 0 alpha, the default is 0. This is so that patches without a stroked edge do not have points outside of the filled region report as “in” due to an invisible edge.

Return type:

bool

Notes

The proper use of this method depends on the transform of the patch. Isolated patches do not have a transform. In this case, the patch creation coordinates and the point coordinates match. The following example checks that the center of a circle is within the circle

>>> center = 0, 0
>>> c = Circle(center, radius=1)
>>> c.contains_point(center)
True

The convention of checking against the transformed patch stems from the fact that this method is predominantly used to check if display coordinates (e.g. from mouse events) are within the patch. If you want to do the above check with data coordinates, you have to properly transform them first:

>>> center = 0, 0
>>> c = Circle(center, radius=3)
>>> plt.gca().add_patch(c)
>>> transformed_interior_point = c.get_data_transform().transform((0, 2))
>>> c.contains_point(transformed_interior_point)
True

contains_points(points, radius=None)

Return whether the given points are inside the patch.

Parameters:

• points ((N, 2) array) – The points to check, in target coordinates of self.get_transform(). These are display coordinates for patches that are added to a figure or Axes. Columns contain x and y values.

• radius (float, optional) –

  Additional margin on the patch in target coordinates of .Patch.get_transform. See .Path.contains_point for further details.

  If None, the default value depends on the state of the object:

  • If .Artist.get_picker is a number, the default is that value. This is so that picking works as expected.

  • Otherwise if the edge color has a non-zero alpha, the default is half of the linewidth. This is so that all the colored pixels are “in” the patch.

  • Finally, if the edge has 0 alpha, the default is 0. This is so that patches without a stroked edge do not have points outside of the filled region report as “in” due to an invisible edge.

Return type:

length-N bool array

Notes

The proper use of this method depends on the transform of the patch. See the notes on .Patch.contains_point.

update_from(other)

Copy properties from other to self.

get_extents()

Return the Patch’s axis-aligned extents as a ~.transforms.Bbox.

get_transform()

Return the ~.transforms.Transform applied to the Patch.

get_data_transform()

Return the ~.transforms.Transform mapping data coordinates to physical coordinates.

get_patch_transform()

Return the ~.transforms.Transform instance mapping patch coordinates to data coordinates.

For example, one may define a patch of a circle which represents a radius of 5 by providing coordinates for a unit circle, and a transform which scales the coordinates (the patch coordinate) by 5.

get_antialiased()

Return whether antialiasing is used for drawing.

get_edgecolor()

Return the edge color.

get_facecolor()

Return the face color.

get_hatchcolor()

Return the hatch color.

get_linewidth()

Return the line width in points.

get_linestyle()

Return the linestyle.

set_antialiased(aa)

Set whether to use antialiased rendering.

Parameters:

aa (bool or None)

set_edgecolor(color)

Set the patch edge color.

Parameters:

color (:mpltype:`color` or None)

set_facecolor(color)

Set the patch face color.

Parameters:

color (:mpltype:`color` or None)

set_color(c)

Set both the edgecolor and the facecolor.

Parameters:

c (:mpltype:`color`)

See also

Patch.set_facecolor, Patch.set_edgecolor

set_hatchcolor(color)

Set the patch hatch color.

Parameters:

color (:mpltype:`color` or ‘edge’ or None)

get_edgegapcolor()

Return the edge gap color.

Added in version 3.11.

See also ~.Patch.set_edgegapcolor.

set_edgegapcolor(edgegapcolor)

Set a color to fill the gaps in the dashed edge style.

Added in version 3.11.

Note

Striped edges are created by drawing two interleaved dashed lines. There can be overlaps between those two, which may result in artifacts when using transparency.

This functionality is experimental and may change.

Parameters:

edgegapcolor (:mpltype:`color` or None) – The color with which to fill the gaps. If None, the gaps are unfilled.

set_alpha(alpha)

Set the alpha value used for blending - not supported on all backends.

Parameters:

alpha (float or None) – alpha must be within the 0-1 range, inclusive.

set_linewidth(w)

Set the patch linewidth in points.

Parameters:

w (float or None)

set_linestyle(ls)

Set the patch linestyle.

Parameters:

ls ({'-', '--', '-.', ':', '', ...} or (offset, on-off-seq)) –

Possible values:

• A string:

  linestyle	description
  '-' or 'solid'	solid line
  '--' or 'dashed'	dashed line
  '-.' or 'dashdot'	dash-dotted line
  ':' or 'dotted'	dotted line
  '' or 'none' (discouraged: 'None', ' ')	draw nothing

• A tuple describing the start position and lengths of dashes and spaces:

  (offset, onoffseq)

  where

  • offset is a float specifying the offset (in points); i.e. how much is the dash pattern shifted.

  • onoffseq is a sequence of on and off ink in points. There can be arbitrary many pairs of on and off values.

  Example: The tuple (0, (10, 5, 1, 5)) means that the pattern starts at the beginning of the line. It draws a 10 point long dash, then a 5 point long space, then a 1 point long dash, followed by a 5 point long space, and then the pattern repeats.

For examples see /gallery/lines_bars_and_markers/linestyles.

set_fill(b)

Set whether to fill the patch.

Parameters:

b (bool)

get_fill()

Return whether the patch is filled.

property fill

Return whether the patch is filled.

set_capstyle(s)

Set the .CapStyle.

The default capstyle is ‘round’ for .FancyArrowPatch and ‘butt’ for all other patches.

Parameters:

s (.CapStyle or {‘butt’, ‘projecting’, ‘round’})

get_capstyle()

Return the capstyle.

set_joinstyle(s)

Set the .JoinStyle.

The default joinstyle is ‘round’ for .FancyArrowPatch and ‘miter’ for all other patches.

Parameters:

s (.JoinStyle or {‘miter’, ‘round’, ‘bevel’})

get_joinstyle()

Return the joinstyle.

set_hatch(hatch)

Set the hatching pattern.

hatch can be one of:

/   - diagonal hatching
\   - back diagonal
|   - vertical
-   - horizontal
+   - crossed
x   - crossed diagonal
o   - small circle
O   - large circle
.   - dots
*   - stars

Letters can be combined, in which case all the specified hatchings are done. If same letter repeats, it increases the density of hatching of that pattern.

Parameters:

hatch ({'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'})

get_hatch()

Return the hatching pattern.

set_hatch_linewidth(lw)

Set the hatch linewidth.

get_hatch_linewidth()

Return the hatch linewidth.

draw(renderer)

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (.Artist.get_visible returns False).

Parameters:

renderer (~matplotlib.backend_bases.RendererBase subclass.)

Notes

This method is overridden in the Artist subclasses.

get_path()

Return the path of this patch.

get_window_extent(renderer=None)

Get the artist’s bounding box in display space, ignoring clipping.

The bounding box’s width and height are non-negative.

Subclasses should override for inclusion in the bounding box “tight” calculation. Default is to return an empty bounding box at 0, 0.

Warning

The extent can change due to any changes in the transform stack, such as changing the Axes limits, the figure size, the canvas used (as is done when saving a figure), or the DPI.

Relying on a once-retrieved window extent can lead to unexpected behavior in various cases such as interactive figures being resized or moved to a screen with different dpi, or figures that look fine on screen render incorrectly when saved to file.

To get accurate results you may need to manually call ~.Figure.savefig or ~.Figure.draw_without_rendering to have Matplotlib compute the rendered size.

Parameters:

renderer (~matplotlib.backend_bases.RendererBase, optional) – Renderer used to draw the figure (i.e. fig.canvas.get_renderer()).

See also

Artist.get_tightbbox

Get the artist bounding box, taking clipping into account.

get_aa()

Alias for get_antialiased.

get_ec()

Alias for get_edgecolor.

get_fc()

Alias for get_facecolor.

get_ls()

Alias for get_linestyle.

get_lw()

Alias for get_linewidth.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, capstyle=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, edgegapcolor=<UNSET>, facecolor=<UNSET>, fill=<UNSET>, gid=<UNSET>, hatch=<UNSET>, hatch_linewidth=<UNSET>, hatchcolor=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: unknown animated: bool antialiased: bool or None capstyle: .CapStyle or {‘butt’, ‘projecting’, ‘round’} clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None color: :mpltype:`color` edgecolor: :mpltype:`color` or None edgegapcolor: :mpltype:`color` or None facecolor: :mpltype:`color` or None figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure fill: bool gid: str hatch: {‘/’, ‘\’, ‘|’, ‘-’, ‘+’, ‘x’, ‘o’, ‘O’, ‘.’, ‘*’} hatch_linewidth: unknown hatchcolor: :mpltype:`color` or ‘edge’ or None in_layout: bool joinstyle: .JoinStyle or {‘miter’, ‘round’, ‘bevel’} label: object linestyle: {‘-’, ‘–’, ‘-.’, ‘:’, ‘’, …} or (offset, on-off-seq) linewidth: float or None mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

set_aa(aa)

Alias for set_antialiased.

set_ec(color)

Alias for set_edgecolor.

set_fc(color)

Alias for set_facecolor.

set_ls(ls)

Alias for set_linestyle.

set_lw(w)

Alias for set_linewidth.

class qdiv.plot.ordination_plots.TextPath(xy, s, size=None, prop=None, _interpolation_steps=1, usetex=False)

Bases: Path

Create a path from the text.

Create a path from the text. Note that it simply is a path, not an artist. You need to use the .PathPatch (or other artists) to draw this path onto the canvas.

Parameters:

• xy (tuple or array of two float values) – Position of the text. For no offset, use xy=(0, 0).

• s (str) – The text to convert to a path.

• size (float, optional) – Font size in points. Defaults to the size specified via the font properties prop.

• prop (~matplotlib.font_manager.FontProperties, optional) – Font property. If not provided, will use a default .FontProperties with parameters from the rcParams.

• _interpolation_steps (int, optional) – (Currently ignored)

• usetex (bool, default: False) – Whether to use tex rendering.

Examples

The following creates a path from the string “ABC” with Helvetica font face; and another path from the latex fraction 1/2:

from matplotlib.text import TextPath
from matplotlib.font_manager import FontProperties

fp = FontProperties(family="Helvetica", style="italic")
path1 = TextPath((12, 12), "ABC", size=12, prop=fp)
path2 = TextPath((0, 0), r"$\frac{1}{2}$", size=12, usetex=True)

Also see /gallery/text_labels_and_annotations/demo_text_path.

set_size(size)

Set the text size.

get_size()

Get the text size.

property vertices

Return the cached path after updating it if necessary.

property codes

Return the codes

class qdiv.plot.ordination_plots.FontProperties(family=None, style=None, variant=None, weight=None, stretch=None, size=None, fname=None, math_fontfamily=None)

Bases: object

A class for storing and manipulating font properties.

The font properties are the six properties described in the W3C Cascading Style Sheet, Level 1 font specification and math_fontfamily for math fonts:

• family: A list of font names in decreasing order of priority. The items may include a generic font family name, either ‘sans-serif’, ‘serif’, ‘cursive’, ‘fantasy’, or ‘monospace’. In that case, the actual font to be used will be looked up from the associated rcParam during the search process in .findfont. Default: :rc:`font.family`

• style: Either ‘normal’, ‘italic’ or ‘oblique’. Default: :rc:`font.style`

• variant: Either ‘normal’ or ‘small-caps’. Default: :rc:`font.variant`

• stretch: A numeric value in the range 0-1000 or one of ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’ or ‘ultra-expanded’. Default: :rc:`font.stretch`

• weight: A numeric value in the range 0-1000 or one of ‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’. Default: :rc:`font.weight`

• size: Either a relative value of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’ or an absolute font size, e.g., 10. Default: :rc:`font.size`

• math_fontfamily: The family of fonts used to render math text. Supported values are: ‘dejavusans’, ‘dejavuserif’, ‘cm’, ‘stix’, ‘stixsans’ and ‘custom’. Default: :rc:`mathtext.fontset`

Alternatively, a font may be specified using the absolute path to a font file, by using the fname kwarg. However, in this case, it is typically simpler to just pass the path (as a pathlib.Path, not a str) to the font kwarg of the .Text object.

The preferred usage of font sizes is to use the relative values, e.g., ‘large’, instead of absolute font sizes, e.g., 12. This approach allows all text sizes to be made larger or smaller based on the font manager’s default font size.

This class accepts a single positional string as fontconfig pattern, or alternatively individual properties as keyword arguments:

FontProperties(pattern)
FontProperties(*, family=None, style=None, variant=None, ...)

This support does not depend on fontconfig; we are merely borrowing its pattern syntax for use here.

Note that Matplotlib’s internal font manager and fontconfig use a different algorithm to lookup fonts, so the results of the same pattern may be different in Matplotlib than in other applications that use fontconfig.

get_family()

Return a list of individual font family names or generic family names.

The font families or generic font families (which will be resolved from their respective rcParams when searching for a matching font) in the order of preference.

get_name()

Return the name of the font that best matches the font properties.

get_style()

Return the font style. Values are: ‘normal’, ‘italic’ or ‘oblique’.

get_variant()

Return the font variant. Values are: ‘normal’ or ‘small-caps’.

get_weight()

Get the font weight. Options are: A numeric value in the range 0-1000 or one of ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’

get_stretch()

Return the font stretch or width. Options are: ‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultra-expanded’.

get_size()

Return the font size.

get_file()

Return the filename of the associated font.

get_fontconfig_pattern()

Get a fontconfig pattern suitable for looking up the font as specified with fontconfig’s fc-match utility.

This support does not depend on fontconfig; we are merely borrowing its pattern syntax for use here.

set_family(family)

Change the font family. Can be either an alias (generic name is CSS parlance), such as: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’, a real font name or a list of real font names. Real font names are not supported when :rc:`text.usetex` is True. Default: :rc:`font.family`

set_style(style)

Set the font style.

Parameters:

style ({‘normal’, ‘italic’, ‘oblique’}, default: :rc:`font.style`)

set_variant(variant)

Set the font variant.

Parameters:

variant ({‘normal’, ‘small-caps’}, default: :rc:`font.variant`)

set_weight(weight)

Set the font weight.

Parameters:

weight (int or {‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’}, default: :rc:`font.weight`) – If int, must be in the range 0-1000.

set_stretch(stretch)

Set the font stretch or width.

Parameters:

stretch (int or {‘ultra-condensed’, ‘extra-condensed’, ‘condensed’, ‘semi-condensed’, ‘normal’, ‘semi-expanded’, ‘expanded’, ‘extra-expanded’, ‘ultra-expanded’}, default: :rc:`font.stretch`) – If int, must be in the range 0-1000.

set_size(size)

Set the font size.

Parameters:

size (float or {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}, default: :rc:`font.size`) – If a float, the font size in points. The string values denote sizes relative to the default font size.

set_file(file)

Set the filename of the fontfile to use. In this case, all other properties will be ignored.

set_fontconfig_pattern(pattern)

Set the properties by parsing a fontconfig pattern.

This support does not depend on fontconfig; we are merely borrowing its pattern syntax for use here.

get_math_fontfamily()

Return the name of the font family used for math text.

The default font is :rc:`mathtext.fontset`.

set_math_fontfamily(fontfamily)

Set the font family for text in math mode.

If not set explicitly, :rc:`mathtext.fontset` will be used.

Parameters:

fontfamily (str) –

The name of the font family.

Available font families are defined in the default matplotlibrc file.

See also

text.Text.get_math_fontfamily

copy()

Return a copy of self.

set_name(family)

Change the font family. Can be either an alias (generic name is CSS parlance), such as: ‘serif’, ‘sans-serif’, ‘cursive’, ‘fantasy’, or ‘monospace’, a real font name or a list of real font names. Real font names are not supported when :rc:`text.usetex` is True. Default: :rc:`font.family`

get_slant()

Return the font style. Values are: ‘normal’, ‘italic’ or ‘oblique’.

set_slant(style)

Set the font style.

Parameters:

style ({‘normal’, ‘italic’, ‘oblique’}, default: :rc:`font.style`)

get_size_in_points()

Return the font size.

qdiv.plot.ordination_plots.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))

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 only the ordination results dictionary. If False, return fig, ax, and the results dictionary.

• 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:

• When return_data=False (default)

• fig (matplotlib.figure.Figure) – Figure object.

• ax (matplotlib.axes.Axes) – Axes object.

• results (dict) – Dictionary containing:

  • meta : Metadata table with ordination coordinates.

  • biplot : Biplot coordinates, when available.

  • pct_explained : Percentage of variation explained by each axis.

  • eigenvalues : Ordination eigenvalues.

  • axis_names : Names of the ordination axes.

  • kind : Ordination type ('pcoa' or 'dbrda').

• When return_data=True

• results (dict) – Same dictionary as above. No figure is created and no Matplotlib objects are returned.

Return type:

Dict[str, Any] | Tuple[Figure, Axes, Dict[str, Any]]

Notes

If return_data=True, no figure is generated and the returned dictionary contains only ordination results and metadata. The fig and ax entries are omitted.

• 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, ax, res = ordination(pcoa_results, meta, color_by="Treatment")
>>> res["meta"]
>>> res["pct_explained"]
>>> res["biplot"]

>>> res = ordination(pcoa_results, meta, return_data=True)
>>> res["meta"]
>>> res["pct_explained"]