skbio.stats.distance.pwmantel¶
- skbio.stats.distance.pwmantel(dms, labels=None, method='pearson', permutations=999, alternative='two-sided', strict=True, lookup=None)[source]¶
Run Mantel tests for every pair of given distance matrices.
State: Experimental as of 0.4.0.
Runs a Mantel test for each pair of distance matrices and collates the results in a
DataFrame
. Distance matrices do not need to be in the same ID order if they areDistanceMatrix
instances. Distance matrices will be re-ordered prior to running each pairwise test, and ifstrict=False
, IDs that don’t match between a pair of distance matrices will be dropped prior to running the test (otherwise aValueError
will be raised if there are nonmatching IDs between any pair of distance matrices).- Parameters:
dms (iterable of DistanceMatrix objects, array_like objects, or filepaths) – to distance matrices. If they are
array_like
, no reordering or matching of IDs will be performed.labels (iterable of str or int, optional) – Labels for each distance matrix in dms. These are used in the results
DataFrame
to identify the pair of distance matrices used in a pairwise Mantel test. IfNone
, defaults to monotonically-increasing integers starting at zero.method ({'pearson', 'spearman'}) – Correlation method. See
mantel
function for more details.permutations (int, optional) – Number of permutations. See
mantel
function for more details.alternative ({'two-sided', 'greater', 'less'}) – Alternative hypothesis. See
mantel
function for more details.strict (bool, optional) – Handling of nonmatching IDs. See
mantel
function for more details.lookup (dict, optional) – Map existing IDs to new IDs. See
mantel
function for more details.
- Returns:
DataFrame
containing the results of each pairwise test (one per row). Includes the number of objects considered in each test as columnn
(after applying lookup and filtering nonmatching IDs ifstrict=False
). Columnp-value
will display p-values asNaN
if p-values could not be computed (they are stored asnp.nan
within theDataFrame
; seemantel
for more details).- Return type:
See also
Notes
Passing a list of filepaths can be useful as it allows for a smaller amount of memory consumption as it only loads two matrices at a time as opposed to loading all distance matrices into memory.
Examples
Import the functionality we’ll use in the following examples:
>>> from skbio import DistanceMatrix >>> from skbio.stats.distance import pwmantel
Define three 3x3 distance matrices:
>>> x = DistanceMatrix([[0, 1, 2], ... [1, 0, 3], ... [2, 3, 0]]) >>> y = DistanceMatrix([[0, 2, 7], ... [2, 0, 6], ... [7, 6, 0]]) >>> z = DistanceMatrix([[0, 5, 6], ... [5, 0, 1], ... [6, 1, 0]])
Run Mantel tests for each pair of distance matrices (there are 3 possible pairs):
>>> pwmantel((x, y, z), labels=('x', 'y', 'z'), ... permutations=0) statistic p-value n method permutations alternative dm1 dm2 x y 0.755929 NaN 3 pearson 0 two-sided z -0.755929 NaN 3 pearson 0 two-sided y z -0.142857 NaN 3 pearson 0 two-sided
Note that we passed
permutations=0
to suppress significance tests; the p-values in the output are labelledNaN
.