docs: def plot_mds(
          self,
          rank="auto",
          metric="braycurtis",
          method="pcoa",
          title=None,
          xlabel=None,
          ylabel=None,
          color=None,
          size=None,
          tooltip=None,
          return_chart=False,
          label=None,
      ):
          """Plot beta diversity distance matrix using multidimensional scaling (MDS).
  
          Parameters
          ----------
          rank : {'auto', 'kingdom', 'phylum', 'class', 'order', 'family', 'genus', 'species'}, optional
              Analysis will be restricted to abundances of taxa at the specified level.
          metric : {'braycurtis', 'manhattan', 'jaccard', 'unifrac', 'unweighted_unifrac}, optional
              Function to use when calculating the distance between two samples.
          method : {'pcoa', 'smacof'}
              Algorithm to use for ordination. PCoA uses eigenvalue decomposition and is not well
              suited to non-euclidean distance functions. SMACOF is an iterative optimization strategy
              that can be used as an alternative.
          title : `string`, optional
              Text label at the top of the plot.
          xlabel : `string`, optional
              Text label along the horizontal axis.
          ylabel : `string`, optional
              Text label along the vertical axis.
          size : `string` or `tuple`, optional
              A string or a tuple containing strings representing metadata fields. The size of points
              in the resulting plot will change based on the metadata associated with each sample.
          color : `string` or `tuple`, optional
              A string or a tuple containing strings representing metadata fields. The color of points
              in the resulting plot will change based on the metadata associated with each sample.
          tooltip : `string` or `list`, optional
              A string or list containing strings representing metadata fields. When a point in the
              plot is hovered over, the value of the metadata associated with that sample will be
              displayed in a modal.
          label : `string` or `callable`, optional
              A metadata field (or function) used to label each analysis. If passing a function, a
              dict containing the metadata for each analysis is passed as the first and only
              positional argument. The callable function must return a string.
  
          Examples
          --------
          Scatter plot of weighted UniFrac distance between all our samples, using counts at the genus
          level.
  
          >>> plot_mds(rank='genus', metric='unifrac')
  
          Notes
          -----
          **For `smacof`**: The values reported on the axis labels are Pearson's correlations between
          the distances between points on each axis alone, and the corresponding distances in the
          distance matrix calculated using the user-specified metric. These values are related to the
          effectiveness of the MDS algorithm in placing points on the scatter plot in such a way that
          they truly represent the calculated distances. They do not reflect how well the distance
          metric captures similarities between the underlying data (in this case, an OTU table).
          """
          if len(self._results) < 2:
              raise OneCodexException("`plot_mds` requires 2 or more valid classification results.")
  
          dists = self._compute_distance(rank, metric).to_data_frame()
  
          # here we figure out what to put in the tooltips and get the appropriate data
          if tooltip:
              if not isinstance(tooltip, list):
                  tooltip = [tooltip]
          else:
              tooltip = []
  
          tooltip.insert(0, "Label")
  
          if color and color not in tooltip:
              tooltip.insert(1, color)
  
          if size and size not in tooltip:
              tooltip.insert(2, size)
  
          magic_metadata, magic_fields = self._metadata_fetch(tooltip, label=label)
  
          if method == "smacof":
              # adapted from https://scikit-learn.org/stable/auto_examples/manifold/plot_mds.html
              x_field = "MDS1"
              y_field = "MDS2"
  
              seed = np.random.RandomState(seed=3)
              mds = manifold.MDS(
                  max_iter=3000, eps=1e-12, random_state=seed, dissimilarity="precomputed", n_jobs=1
              )
              pos = mds.fit(dists).embedding_
              plot_data = pd.DataFrame(pos, columns=[x_field, y_field], index=dists.index)
              plot_data = plot_data.div(plot_data.abs().max(axis=0), axis=1)  # normalize to [0,1]
  
              # determine how much of the original distance is captured by each of the axes after MDS.
              # this implementation of MDS does not use eigen decomposition and so there's no simple
              # way of returning a 'percent of variance explained' value
              r_squared = []
  
              for axis in [0, 1]:
                  mds_dist = pos.copy()
                  mds_dist[::, axis] = 0
                  mds_dist = squareform(euclidean_distances(mds_dist).round(6))
                  r_squared.append(pearsonr(mds_dist, squareform(dists))[0])
  
              # label the axes
              x_extra_label = "r² = %.02f" % (r_squared[0],)
              y_extra_label = "r² = %.02f" % (r_squared[1],)
          elif method == "pcoa":
              # suppress eigenvalue warning from skbio--not because it's an invalid warning, but
              # because lots of folks in the field run pcoa on these distances functions, even if
              # statistically inappropriate. perhaps this will change if we ever become more
              # opinionated about the analyses that we allow our users to do (roo)
              with warnings.catch_warnings():
                  warnings.simplefilter("ignore")
                  ord_result = ordination.pcoa(
                      dists.round(6)
                  )  # round to avoid float precision errors
  
              plot_data = ord_result.samples.iloc[:, [0, 1]]  # get first two components
              plot_data = plot_data.div(plot_data.abs().max(axis=0), axis=1)  # normalize to [0,1]
              plot_data.index = dists.index
              x_field, y_field = plot_data.columns.tolist()  # name of first two components
  
              x_extra_label = "%0.02f%%" % (ord_result.proportion_explained[0] * 100,)
              y_extra_label = "%0.02f%%" % (ord_result.proportion_explained[1] * 100,)
          else:
              raise OneCodexException("MDS method must be one of: smacof, pcoa")
  
          # label the axes
          if xlabel is None:
              xlabel = "{} ({})".format(x_field, x_extra_label)
          if ylabel is None:
              ylabel = "{} ({})".format(y_field, y_extra_label)
  
          plot_data = pd.concat([plot_data, magic_metadata], axis=1).reset_index()
  
          alt_kwargs = dict(
              x=alt.X(x_field, axis=alt.Axis(title=xlabel)),
              y=alt.Y(y_field, axis=alt.Axis(title=ylabel)),
              tooltip=[magic_fields[t] for t in tooltip],
              href="url:N",
              url="https://app.onecodex.com/classification/" + alt.datum.classification_id,
          )
  
          # only add these parameters if they are in use
          if color:
              alt_kwargs["color"] = magic_fields[color]
          if size:
              alt_kwargs["size"] = magic_fields[size]
  
          chart = (
              alt.Chart(plot_data)
              .transform_calculate(url=alt_kwargs.pop("url"))
              .mark_circle()
              .encode(**alt_kwargs)
          )
  
          if title:
              chart = chart.properties(title=title)
  
          if return_chart:
              return chart
          else:
              chart.interactive().display()