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

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])

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

__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])	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')[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”

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