# pointpats.KnoxLocal

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

  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)

  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'})

    Interactive plotting for space-time hotspots.

    Parameters:
      crit float, optional

        critical value for statistical inference, by default 0.05

      inference str, optional

        which p-value to use for determining hotspots. Either “permutation” or “analytic”, by default “permutation”

      radius int, 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_kwds dict, optional

        additional style kewords passed to GeoDataFrame.explore, by default None

      tiles str, optional

        tileset passed to GeoDataFrame.explore tiles argument, by default “CartoDB Positron”

      plot_edges bool, optional

        Whether to include lines drawn between members of a singnificant hotspot, by default True

      edge_weight int, optional

        line thickness when plot_edges=True, by default 2

      edge_color str, optional

        color of line when plot_edges=True, by default “black”

      colors dict, 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)

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

    Parameters:
      dataframe geopandas.GeoDataFrame

        dataframe holding observations. Should be in a projected coordinate system with geometries stored as Points

      time_col str

        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.

      delta int

        delta parameter defining the spatial neighbor threshold measured in the same units as the dataframe CRS

      tau int

        tau parameter defining the temporal neihgbor threshold (in the units measured by time_col)

      permutations int, optional

        permutations to use for computational inference, by default 99

      keep bool

        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)

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

    Parameters:
      crit float, optional

        critical value for statistical inference, by default 0.05

      inference str, 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)

    plot hotspots

    Parameters:
      colors dict, optional

        mapping of colors to hotspot values, by default {“focal”: “red”, “neighbor”: “yellow”, “nonsig”: “grey”}

      crit float, optional

        critical value for assessing statistical sgifnicance, by default 0.05

      inference str, optional

        whether to use permutation or analytic inference, by default “permutation”

      point_kwargs dict, optional

        additional keyword arguments passsed to point plot, by default None

      plot_edges bool, optional

        whether to plot edges connecting members of the same hotspot subgraph, by default True

      edge_color str, optional

        color of edges when plot_edges is True, by default ‘black’

      edge_kwargs dict, optional

        additional keyword arguments passsed to edge plot, by default None

      ax matplotlib.axes.Axes, optional

        axes object on which to create the plot, by default None

    Returns:
      matplotlib.axes.Axes

        plot of local space-time hotspots