Skip to main content
`Ctrl`+`K`

# skbio.stats.distance.permanova

skbio.stats.distance.permanova(distmat, grouping, column=None, permutations=999, seed=None)

  Test for significant differences between groups using PERMANOVA.

  Permutational Multivariate Analysis of Variance (PERMANOVA) is a non-parametric method that tests whether two or more groups of objects (e.g., samples) are significantly different based on a categorical factor. It is conceptually similar to ANOVA except that it operates on distances between objects via a distance matrix, which allows for multivariate analysis. Unlike classical Multivariate Analysis of Variance (MANOVA), PERMANOVA makes no assumptions about the distribution of the underlying data. As such, rather than computing a true F statistic based in known distributions of variables, it computes a pseudo-F statistic whose significance can be assessed by a permutation test.

  The pseudo-F statistic is the ratio of between-group variance to within-group variance, defined in [1] analogously to the F statistic in ANOVA:

  \[F = \frac{{SS}_{between}/(g - 1)}{{SS}_{within}/(n - g)}\]

  It is computed from the sums of squares \({SS}_{between}\) and \({SS}_{within}\) divided by their corresponding degrees of freedom, where \(n\) is the number of distinct objects and \(g\) is the number of groups.

  Statistical significance is assessed via a permutation test. Objects in the distance matrix are assigned to groups (grouping) based on a categorical factor. This assignment of groups is permuted a number of times (controlled via permutations), and a pseudo-F statistic is computed for each permutation. Under the null hypothesis that the groupings of objects have no effect on the distribution of the underlying data, the pseudo-F statistics of these permutations should be identically distributed for a given distance matrix. The probability of a given pseudo-F statistic being at least as extreme as an observed one is then the proportion of permuted pseudo-F statistics (\(F^{\pi}\)) that are greater than or equal to the observed (unpermuted) one (\(F\)):

  \[p = \frac{1 + \text{no. of } F^{\pi} \geq F}{1 + \text{no. of permutations}}\]
  Parameters:
    distmat DistanceMatrix

      Distance matrix containing distances between objects (e.g., distances between samples of microbial communities).

      Changed in version 0.7.0: Renamed from `distance_matrix`. The old name is kept as an alias.

    grouping 1-D array_like or pandas.DataFrame

      Vector indicating the assignment of objects to groups. For example, these could be strings or integers denoting which group an object belongs to. If grouping is 1-D `array_like`, it must be the same length and in the same order as the objects in distmat. If grouping is a `DataFrame`, the column specified by column will be used as the grouping vector. The `DataFrame` must be indexed by the IDs in distmat (i.e., the row labels must be distance matrix IDs), but the order of IDs between distmat and the `DataFrame` need not be the same. All IDs in the distance matrix must be present in the `DataFrame`. Extra IDs in the `DataFrame` are allowed (they are ignored in the calculations).

    column str, optional

      Column name to use as the grouping vector if grouping is a `DataFrame`. Must be provided if grouping is a `DataFrame`. Cannot be provided if grouping is 1-D `array_like`.

    permutations int, optional

      Number of permutations to use when assessing statistical significance. Must be greater than or equal to zero. If zero, statistical significance calculations will be skipped and the p-value will be `np.nan`.

    seed int, Generator or RandomState, optional

      A user-provided random seed or random generator instance. See `details`.

      Added in version 0.6.3.

  Returns:
    pandas.Series

      Results of the statistical test, including `test statistic` and `p-value`.

  See also

  `anosim`
  `statsmodels.multivariate.manova.MANOVA`
  `scipy.stats.permutation_test`

  Notes

  This function uses parallel computation for improved performance. See the parallelization guide for information on controlling the number of threads used.

  Low-level acceleration is available for this function. See scikit-bio-binaries for more information.

  See [1] for the original method reference, as well as `vegan::adonis`, available in R’s vegan package [2].

  The precision of the p-value is dependent on the number of permutations. The default precision is \(0.001=1/(1+999)\) from the default value `permutations=999`. The unpermuted grouping always contributes the first permutation to the numerator and denominator of the p-value, so 1 is added to both. This circumvents the risk of the probability being zero by chance even when it is nonzero. It is suggested in [1] that at least 1000 permutations should be performed for a confidence level of 0.05, and 5000 permutations should be performed for a confidence level of 0.01. The p-value will be `np.nan` if `permutations` is zero.

  A related statistic reported by some implementations (such as `vegan::adonis`) is the \(R^2\) value, which describes the proportion of variance in the data explained by the grouping:

  \[R^2 = \frac{{SS}_{between}}{{SS}_{total}}\]

  This is not currently computed by this function, but it may be derived from the outputs using the following formula:

  \[R^2 = \frac{1}{1 + \frac{n - g}{(g - 1)F}}\]

  where \(F\) is the pseudo-F statistic, \(n\) is the number of objects, and \(g\) is the number of groups.

  References

  [1] (1,2,3)

  Anderson, Marti J. “A new method for non-parametric multivariate analysis of variance.” Austral Ecology 26.1 (2001): 32-46.

  [2]

  http://cran.r-project.org/web/packages/vegan/index.html

  Examples

  See `skbio.stats.distance.anosim` for usage examples (both functions provide similar interfaces).