# 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
>>> 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”

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