pointpats.KnoxLocal¶

class pointpats.KnoxLocal(s_coords, t_coords, delta, tau, permutations=99, keep=False, crit=0.05, crs=None, ids=None)[source]¶

Local Knox statistics for space-time interactions

Parameters:

s_coords: array (nx2): spatial coordinates of point events
t_coords: array (nx1): temporal coordinates of point events (floats or ints, not dateTime)
delta: float: spatial threshold defining distance below which pairs are spatial neighbors
tau: float: temporal threshold defining distance below which pairs are temporal neighbors
permutations: int: number of random permutations for inference
keep: bool: whether to store realized values of the statistic under permutations
conditional: bool: whether to include conditional permutation inference
crit: float: signifcance level for local statistics
crs: str (optional): coordinate reference system string for s_coords

Attributes:

s_coords: array (nx2): spatial coordinates of point events
t_coords: array (nx1): temporal coordinates of point events (floats or ints, not dateTime)
delta: float: spatial threshold defining distance below which pairs are spatial neighbors
tau: float: temporal threshold defining distance below which pairs are temporal neighbors
permutations: int: number of random permutations for inference
keep: bool: whether to store realized values of the statistic under permutations
nst: int: number of space-time pairs (global)
p_poisson: float: Analytical p-value under Poisson assumption (global)
p_sim: float: Pseudo p-value based on random permutations (global)
expected: array: Two-by-two array with expected counts under the null of no space-time interactions. [[NST, NS_], [NT_, N__]] where NST is the expected number of space-time pairs, NS_ is the expected number of spatial (but not also temporal) pairs, NT_ is the number of expected temporal (but not also spatial pairs), N__ is the number of pairs that are neighor spatial or temporal neighbors. (global)
observed: array: Same structure as expected with the observed pair classifications (global)
sim: array: Global statistics from permutations (if keep=True and keep=True) (global)
p_sims: array: Local psuedo p-values from conditional permutations (if permutations>0)
sims: array: Local statistics from conditional permutations (if keep=True and permutations>0)
nsti: array: Local statistics
p_hypergeom: array: Analytical p-values based on hypergeometric distribution

Notes

Technical details can be found in [Rog01]. The conditional permutation inference is unique to pysal.pointpats.

Examples¶

>>> import libpysal
>>> path = libpysal.examples.get_path('burkitt.shp')
>>> import geopandas
>>> df = geopandas.read_file(path)
>>> from pointpats.spacetime import Knox
>>> import numpy
>>> numpy.random.seed(12345)
>>> local_knox = KnoxLocal(df[['X', 'Y']], df[["T"]], delta=20, tau=5, keep=True)
>>> local_knox.statistic_.shape
(188,)
>>> lres = local_knox
>>> gt0ids = numpy.where(lres.nsti>0)
>>> gt0ids 
(array([ 25,  26,  30,  31,  35,  36,  41,  42,  46,  47,  51,  52, 102,
          103, 116, 118, 122, 123, 137, 138, 139, 140, 158, 159, 162, 163]),)
>>> lres.nsti[gt0ids]
array([1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
       1., 1., 1., 1., 1., 1., 1., 1., 1.])
>>> lres.p_hypergeom[gt0ids]
array([0.1348993 , 0.14220663, 0.07335085, 0.08400282, 0.1494317 ,
       0.21524073, 0.0175806 , 0.04599869, 0.17523687, 0.18209188,
       0.19111321, 0.16830444, 0.13734428, 0.14703242, 0.06796364,
       0.03192559, 0.13734428, 0.17523687, 0.12998154, 0.1933476 ,
       0.13244507, 0.13244507, 0.12502644, 0.14703242, 0.12502644,
       0.12998154])
>>> lres.p_sims[gt0ids]
array([0.3 , 0.33, 0.11, 0.17, 0.3 , 0.42, 0.06, 0.06, 0.33, 0.34, 0.36,
       0.38, 0.3 , 0.29, 0.41, 0.19, 0.31, 0.39, 0.18, 0.39, 0.48, 0.41,
       0.22, 0.41, 0.39, 0.32])

__init__(s_coords, t_coords, delta, tau, permutations=99, keep=False, crit=0.05, crs=None, ids=None)[source]¶

Methods

`__init__`(s_coords, t_coords, delta, tau[, ...])
`explore`([crit, inference, radius, ...])	Interactive plotting for space-time hotspots.
`from_dataframe`(dataframe, time_col, delta, tau)	Compute a set of local Knox statistics from a dataframe of Point observations
`hotspots`([crit, inference, keep_neighbors])	Table of significant space-time clusters that define local hotspots.
`plot`([colors, crit, inference, ...])	plot hotspots

explore(crit: float = 0.05, inference: str = 'permutation', radius: int = 5, style_kwds: dict = None, tiles: str = 'CartoDB Positron', plot_edges: bool = True, edge_weight: int = 2, edge_color: str = 'black', colors: dict = {'focal': 'red', 'neighbor': 'yellow', 'nonsig': 'grey'})[source]¶

Interactive plotting for space-time hotspots.

Parameters:

critfloat, optional: critical value for statistical inference, by default 0.05
inferencestr, optional: which p-value to use for determining hotspots. Either “permutation” or “analytic”, by default “permutation”
radiusint, optional: radius of the circlemarker plotted by folium, passed to geopandas.GeoDataFrame.explore style_kwds as a convenience. Ignored if style_kwds is passed directly, by default 5
style_kwdsdict, optional: additional style kewords passed to GeoDataFrame.explore, by default None
tilesstr, optional: tileset passed to GeoDataFrame.explore tiles argument, by default “CartoDB Positron”
plot_edgesbool, optional: Whether to include lines drawn between members of a singnificant hotspot, by default True
edge_weightint, optional: line thickness when plot_edges=True, by default 2
edge_colorstr, optional: color of line when plot_edges=True, by default “black”
colorsdict, optional: mapping of observation type to color, by default {“focal”: “red”, “neighbor”: “yellow”, “nonsig”: “grey”}

Returns:

folium.Map: an interactive map showing locally-significant spacetime hotspots

classmethod from_dataframe(dataframe, time_col: str, delta: int, tau: int, permutations: int = 99, keep: bool = False)[source]¶

Compute a set of local Knox statistics from a dataframe of Point observations

Parameters:

dataframegeopandas.GeoDataFrame: dataframe holding observations. Should be in a projected coordinate system with geometries stored as Points
time_colstr: column in the dataframe storing the time values (integer coordinate) for each observation. For example if the observations are stored with a timestamp, the time_col should be converted to a series of integers representing, e.g. hours, days, seconds, etc.
deltaint: delta parameter defining the spatial neighbor threshold measured in the same units as the dataframe CRS
tauint: tau parameter defining the temporal neihgbor threshold (in the units measured by time_col)
permutationsint, optional: permutations to use for computational inference, by default 99
keepbool: whether to store realized values of the statistic under permutations

Returns:

pointpats.spacetime.LocalKnox: a fitted KnoxLocal class

hotspots(crit=0.05, inference='permutation', keep_neighbors=True)[source]¶

Table of significant space-time clusters that define local hotspots.

Parameters:

critfloat, optional: critical value for statistical inference, by default 0.05
inferencestr, optional: whether p-values should use permutation or analutical inference, by default “permutation”
keep_neighbors: bool: whether to included nonsignificant members of hotspots. While these observations are not themselves significant, these still define the spatial extent of the cluster, and the the focal observation cannot become significant without their presence. If True, return all members of a significant hotspot, else return only the significant locations

Returns:

pandas.DataFrame: dataframe of significant hotspots

Raises:

ValueError: if inference is not in {‘permutation’, ‘analytic’}

plot(colors: dict = {'focal': 'red', 'neighbor': 'yellow', 'nonsig': 'grey'}, crit: float = 0.05, inference: str = 'permutation', point_kwargs: dict = None, plot_edges: bool = True, edge_color: str = 'black', edge_kwargs: dict = None, ax=None)[source]¶

plot hotspots

Parameters:

colorsdict, optional: mapping of colors to hotspot values, by default {“focal”: “red”, “neighbor”: “yellow”, “nonsig”: “grey”}
critfloat, optional: critical value for assessing statistical sgifnicance, by default 0.05
inferencestr, optional: whether to use permutation or analytic inference, by default “permutation”
point_kwargsdict, optional: additional keyword arguments passsed to point plot, by default None
plot_edgesbool, optional: whether to plot edges connecting members of the same hotspot subgraph, by default True
edge_colorstr, optional: color of edges when plot_edges is True, by default ‘black’
edge_kwargsdict, optional: additional keyword arguments passsed to edge plot, by default None
axmatplotlib.axes.Axes, optional: axes object on which to create the plot, by default None

Returns:

matplotlib.axes.Axes: plot of local space-time hotspots