def mantel(s_coords, t_coords, permutations=99, scon=1.0, spow=-1.0, tcon=1.0, tpow=-1.0):
"""
Standardized Mantel test for spatio-temporal interaction. [Mantel1967]_
Parameters
----------
s_coords : array
(n, 2), spatial coordinates.
t_coords : array
(n, 1), temporal coordinates.
permutations : int, optional
the number of permutations used to establish pseudo-
significance (the default is 99).
scon : float, optional
constant added to spatial distances (the default is 1.0).
spow : float, optional
value for power transformation for spatial distances
(the default is -1.0).
tcon : float, optional
constant added to temporal distances (the default is 1.0).
tpow : float, optional
value for power transformation for temporal distances
(the default is -1.0).
Returns
-------
mantel_result : dictionary
contains the statistic (stat) for the test and the
associated p-value (pvalue).
stat : float
value of the knox test for the dataset.
pvalue : float
pseudo p-value associated with the statistic.
Examples
--------
>>> import numpy as np
>>> import pysal
Read in the example data and create an instance of SpaceTimeEvents.
>>> path = pysal.examples.get_path("burkitt.shp")
>>> events = SpaceTimeEvents(path,'T')
Set the random seed generator. This is used by the permutation based
inference to replicate the pseudo-significance of our example results -
the end-user will normally omit this step.
>>> np.random.seed(100)
The standardized Mantel test is a measure of matrix correlation between
the spatial and temporal distance matrices of the event dataset. The
following example runs the standardized Mantel test without a constant
or transformation; however, as recommended by Mantel (1967) [2]_, these
should be added by the user. This can be done by adjusting the constant
and power parameters.
>>> result = mantel(events.space, events.t, 99, scon=1.0, spow=-1.0, tcon=1.0, tpow=-1.0)
Next, we examine the result of the test.
>>> print("%6.6f"%result['stat'])
0.048368
Finally, we look at the pseudo-significance of this value, calculated by
permuting the timestamps and rerunning the statistic for each of the 99
permutations. According to these parameters, the results indicate
space-time interaction between the events.
>>> print("%2.2f"%result['pvalue'])
0.01
"""
t = t_coords
s = s_coords
n = len(t)
# calculate the spatial and temporal distance matrices for the events
distmat = cg.distance_matrix(s)
timemat = cg.distance_matrix(t)
# calculate the transformed standardized statistic
timevec = (util.get_lower(timemat) + tcon) ** tpow
distvec = (util.get_lower(distmat) + scon) ** spow
stat = stats.pearsonr(timevec, distvec)[0].sum()
# return the results (if no inference)
if not permutations:
return stat
# loop for generating a random distribution to assess significance
dist = []
for i in range(permutations):
trand = util.shuffle_matrix(timemat, range(n))
timevec = (util.get_lower(trand) + tcon) ** tpow
m = stats.pearsonr(timevec, distvec)[0].sum()
dist.append(m)
## establish the pseudo significance of the observed statistic
distribution = np.array(dist)
greater = np.ma.masked_greater_equal(distribution, stat)
count = np.ma.count_masked(greater)
pvalue = (count + 1.0) / (permutations + 1.0)
# report the results
mantel_result = {'stat': stat, 'pvalue': pvalue}
return mantel_result
def mantel(s_coords,
t_coords,
permutations=99,
scon=1.0,
spow=-1.0,
tcon=1.0,
tpow=-1.0):
"""
Standardized Mantel test for spatio-temporal interaction. [2]_
Parameters
----------
s_coords : array
nx2 spatial coordinates
t_coords : array
nx1 temporal coordinates
permutations : int
the number of permutations used to establish pseudo-
significance (default is 99)
scon : float
constant added to spatial distances
spow : float
value for power transformation for spatial distances
tcon : float
constant added to temporal distances
tpow : float
value for power transformation for temporal distances
Returns
-------
mantel_result : dictionary
contains the statistic (stat) for the test and the
associated p-value (pvalue)
stat : float
value of the knox test for the dataset
pvalue : float
pseudo p-value associated with the statistic
References
----------
.. [2] N. Mantel. 1967. The detection of disease clustering and a
generalized regression approach. Cancer Research, 27(2):209-220.
Examples
--------
>>> import numpy as np
>>> import pysal
Read in the example data and create an instance of SpaceTimeEvents.
>>> path = pysal.examples.get_path("burkitt")
>>> events = SpaceTimeEvents(path,'T')
Set the random seed generator. This is used by the permutation based
inference to replicate the pseudo-significance of our example results -
the end-user will normally omit this step.
>>> np.random.seed(100)
The standardized Mantel test is a measure of matrix correlation between
the spatial and temporal distance matrices of the event dataset. The
following example runs the standardized Mantel test without a constant
or transformation; however, as recommended by Mantel (1967) [2]_, these
should be added by the user. This can be done by adjusting the constant
and power parameters.
>>> result = mantel(events.space, events.t, 99, scon=1.0, spow=-1.0, tcon=1.0, tpow=-1.0)
Next, we examine the result of the test.
>>> print("%6.6f"%result['stat'])
0.048368
Finally, we look at the pseudo-significance of this value, calculated by
permuting the timestamps and rerunning the statistic for each of the 99
permutations. According to these parameters, the results indicate
space-time interaction between the events.
>>> print("%2.2f"%result['pvalue'])
0.01
"""
t = t_coords
s = s_coords
n = len(t)
# calculate the spatial and temporal distance matrices for the events
distmat = cg.distance_matrix(s)
timemat = cg.distance_matrix(t)
# calculate the transformed standardized statistic
timevec = (util.get_lower(timemat) + tcon)**tpow
distvec = (util.get_lower(distmat) + scon)**spow
stat = stats.pearsonr(timevec, distvec)[0].sum()
# return the results (if no inference)
if not permutations:
return stat
# loop for generating a random distribution to assess significance
dist = []
for i in range(permutations):
trand = util.shuffle_matrix(timemat, range(n))
timevec = (util.get_lower(trand) + tcon)**tpow
m = stats.pearsonr(timevec, distvec)[0].sum()
dist.append(m)
## establish the pseudo significance of the observed statistic
distribution = np.array(dist)
greater = np.ma.masked_greater_equal(distribution, stat)
count = np.ma.count_masked(greater)
pvalue = (count + 1.0) / (permutations + 1.0)
# report the results
mantel_result = {'stat': stat, 'pvalue': pvalue}
return mantel_result
def test_get_lower(self):
np.random.seed(10)
obs = util.get_lower(self.X).flatten().tolist()
exp = [4, 8, 9, 12, 13, 14]
for i in range(6):
self.assertEqual(exp[i], obs[i])
