Skip to main content
`Ctrl`+`K`

# skbio.stats.ordination.OrdinationResults.plot

OrdinationResults.plot(df=None, column=None, axes=None, axis_labels=None, title='', cmap=None, s=20, centroids=False, confidence_ellipses=False)

  Create a scatterplot of ordination results colored by metadata.

  Creates a scatterplot of the ordination results, where each point represents a sample. Optionally, these points can be colored by metadata (see df and column below).

  Parameters:
    df pd.DataFrame, optional

      `DataFrame` containing sample metadata. Must be indexed by sample ID, and all sample IDs in the ordination results must exist in the `DataFrame`. If `None`, samples (i.e., points) will not be colored by metadata.

    column str, optional

      Column name in df to color samples (i.e., points in the plot) by. Cannot have missing data (i.e., `np.nan`). column can be numeric or categorical. If numeric, all values in the column will be cast to `float` and mapped to colors using cmap. A colorbar will be included to serve as a legend. If categorical (i.e., not all values in column could be cast to `float`), colors will be chosen for each category using evenly-spaced points along cmap. A legend will be included. If `None`, samples (i.e., points) will not be colored by metadata.

    axes iterable of int, optional

      Indices of sample coordinates to plot. Must contain exactly two or three elements, for 2D or 3D plots, respectively. For example, `axes=(0, 1, 2)` (default if there are three or more dimensions) will create a 3D plot with PC1 on the x-axis, PC2 on the y-axis, and PC3 on the z-axis. `axes=(0, 1)` (default if there are only two dimensions) will create a 2D plot with PC1 on the x-axis and PC2 on the y-axis.

    axis_labels iterable of str, optional

      Labels for the x-, y-, and z-axes. If `None`, labels will be the values of axes cast as strings.

    title str, optional

      Plot title.

    cmap str or matplotlib.colors.Colormap, optional

      Name or instance of matplotlib colormap to use for mapping column values to colors. If `None`, defaults to the colormap specified in the matplotlib rc file. Qualitative colormaps (e.g., `Set1`) are recommended for categorical data, while sequential colormaps (e.g., `Greys`) are recommended for numeric data. See [1] for these colormap classifications.

    s scalar or iterable of scalars, optional

      Size of points. See matplotlib’s `Axes3D.scatter` documentation for more details.

    centroids bool, optional

      If True, plot the centroids of each category in column.

    confidence_ellipses bool, optional

      If True, plot confidence ellipses for each category in column. Ellipses are calculated using to fit an interval of 2 standard deviations using the covariance of the points. Only supported for 2D plots.

  Returns:
    matplotlib.figure.Figure

      Figure containing the scatterplot and legend/colorbar if metadata were provided.

  Raises:
    ValueError

      Raised on invalid input, including the following situations:

      - there are not at least two dimensions to plot

      - there are not exactly two or three values in axes, they are not unique, or are out of range

      - there are not exactly two or three values in axis_labels

      - either df or column is provided without the other

      - column is not in the `DataFrame`

      - sample IDs in the ordination results are not in df or have missing data in column

      - confidence ellipses are requested for 3D plots

  Notes

  This method creates basic plots of ordination results, and is intended to provide a quick look at the results in the context of metadata (e.g., from within the Jupyter Lab). For more customization and to generate publication-quality figures, we recommend EMPeror [2].

  References

  [1]

  http://matplotlib.org/examples/color/colormaps_reference.html

  [2]

  EMPeror: a tool for visualizing high-throughput microbial community data. Vazquez-Baeza Y, Pirrung M, Gonzalez A, Knight R. Gigascience. 2013 Nov 26;2(1):16. http://biocore.github.io/emperor/

  Examples

  Define a distance matrix with four samples labelled A-D:

      >>> from skbio import DistanceMatrix
      >>> dm = DistanceMatrix([[0., 0.21712454, 0.5007512, 0.91769271],
      ...                      [0.21712454, 0., 0.45995501, 0.80332382],
      ...                      [0.5007512, 0.45995501, 0., 0.65463348],
      ...                      [0.91769271, 0.80332382, 0.65463348, 0.]],
      ...                     ['A', 'B', 'C', 'D'])

  Define metadata for each sample in a `pandas.DataFrame`:

      >>> import pandas as pd
      >>> metadata = {
      ...     'A': {'body_site': 'skin'},
      ...     'B': {'body_site': 'gut'},
      ...     'C': {'body_site': 'gut'},
      ...     'D': {'body_site': 'skin'}}
      >>> df = pd.DataFrame.from_dict(metadata, orient='index')

  Run principal coordinate analysis (PCoA) on the distance matrix:

      >>> from skbio.stats.ordination import pcoa
      >>> pcoa_results = pcoa(dm)

  Plot the ordination results, where each sample is colored by body site (a categorical variable):

      >>> fig = pcoa_results.plot(
      ...     df=df, column='body_site',
      ...     title='Samples colored by body site',
      ...     cmap='Set1', s=50
      ... )