qdiv.stats.mantel

qdiv.stats.mantel(dis1, dis2, method='spearman', getOnlyStat=False, permutations=999, *, random_state=None, **kwargs)[source]

Perform a Mantel test to assess the association between two dissimilarity matrices.

The Mantel test evaluates whether pairs of samples that are close (or far apart) in one dissimilarity matrix tend to be close (or far apart) in another. The test statistic is computed by comparing the lower‑triangular entries of the two matrices, and statistical significance is assessed using a permutation test.

For correlation-based methods, the association is quantified as a dissimilarity (1 − r), where r is the Pearson or Spearman correlation between the vectorized distance matrices.

Parameters:

  • dis1 (pandas.DataFrame) – First square distance or dissimilarity matrix (samples × samples) with identical row and column labels.

  • dis2 (pandas.DataFrame) – Second square distance or dissimilarity matrix (samples × samples) with identical row and column labels matching dis1.

  • method ({'spearman', 'pearson', 'absDist'}, default='spearman') –

    Measure used to quantify association between distance matrices:

    • ’spearman’ :

      Spearman rank correlation between distances (reported as 1 − ρ).

    • ’pearson’ :

      Pearson correlation between distances (reported as 1 − r).

    • ’absDist’ :

      Mean absolute difference between corresponding distances.

  • getOnlyStat (bool, default=False) – If True, return only the observed test statistic without performing permutations.

  • permutations (int, default=999) – Number of permutations used to approximate the null distribution.

  • random_state (int | numpy.random.Generator | None) – Random seed or NumPy random generator for reproducible permutations.

Returns:

  • If getOnlyStat=True, returns the observed statistic only.

  • Otherwise, returns a list containing the observed statistic and its permutation-based p-value.

Return type:

float or list [statistic, p_value]

Notes

  • The test uses only the lower triangular part of each distance matrix (excluding the diagonal), avoiding double counting of pairwise distances.

  • Sample labels are permuted in dis1 while dis2 is held fixed to generate the null distribution.

  • For correlation-based methods (‘pearson’, ‘spearman’), the reported statistic is a dissimilarity (1 − r or 1 − ρ), so smaller values indicate stronger association between the two matrices.

  • p-values are computed using a standard permutation test with a +1 correction: (count + 1) / (permutations + 1).