Skip to main content
`Ctrl`+`K`

# skbio.diversity.beta_diversity

skbio.diversity.beta_diversity(metric, counts, ids=None, validate=True, pairwise_func=None, **kwargs)

  Compute distances between all pairs of samples.

  Parameters:
    metric str, callable

      The pairwise distance function to apply. See the scipy `pdist` docs and the scikit-bio functions linked under See Also for available metrics. Passing metrics as a strings is preferable as this often results in an optimized version of the metric being used.

    counts 2D array_like of ints or floats, 2D pandas DataFrame, Table

      Matrix containing count/abundance data where each row contains counts of taxa in a given sample.

    ids iterable of strs, optional

      Identifiers for each sample in `counts`. By default, samples will be assigned integer identifiers in the order that they were provided (where the type of the identifiers will be `str`).

    validate bool, optional

      If `False`, validation of the input won’t be performed. This step can be slow, so if validation is run elsewhere it can be disabled here. However, invalid input data can lead to invalid results or error messages that are hard to interpret, so this step should not be bypassed if you’re not certain that your input data are valid. See `skbio.diversity` for the description of what validation entails so you can determine if you can safely disable validation.

    pairwise_func callable, optional

      The function to use for computing pairwise distances. This function must take `counts` and `metric` and return a square, hollow, 2-D `numpy.ndarray` of dissimilarities (floats). Examples of functions that can be provided are `scipy.spatial.distance.pdist` and `sklearn.metrics.pairwise_distances`. By default, `scipy.spatial.distance.pdist` will be used.

    kwargs kwargs, optional

      Metric-specific parameters.

  Returns:
    skbio.DistanceMatrix

      Distances between all pairs of samples (i.e., rows). The number of rows and columns will be equal to the number of rows in `counts`.

  Raises:
    ValueError, MissingNodeError, DuplicateNodeError

      If validation fails. Exact error will depend on what was invalid.

    iTypeError

      If invalid method-specific parameters are provided.

  See also

  `skbio.diversity`
  `skbio.diversity.beta`
  `skbio.diversity.get_beta_diversity_metrics`
  `skbio.diversity.alpha_diversity`
  `scipy.spatial.distance.pdist`
  `sklearn.metrics.pairwise_distances`