pointpats.QStatistic

class pointpats.QStatistic(pp, shape='rectangle', nx=3, ny=3, rectangle_width=0, rectangle_height=0, lh=10, realizations=0, window=None, rng=None)[source]

Pearson chi-square quadrat test for complete spatial randomness (CSR).

This class partitions the study region into quadrats (rectangles or hexagons), counts the number of events falling in each quadrat, and evaluates departure from CSR using a Pearson chi-square statistic under an equal-intensity CSR null model.

The primary outputs are the observed chi-square statistic and its analytical p-value (from the chi-square distribution). Optionally, a simulation-based (Monte Carlo) p-value can be computed by generating CSR realizations within the study window and recomputing the chi-square statistic for each realization.

Parameters:
pp:class: .PointPattern or array_like

Event coordinates as an (n, 2) array-like of floats (x, y).

shape{“rectangle”, “hexagon”}, default=”rectangle”

Quadrat tessellation type.

nxint, default=3

Number of columns when shape=”rectangle” and rectangle_width / rectangle_height are not provided.

nyint, default=3

Number of rows when shape=”rectangle” and rectangle_width / rectangle_height are not provided.

rectangle_widthfloat, default=0

Target rectangle width. Must be provided together with rectangle_height. When both are provided and non-zero, nx and ny are ignored and the grid dimensions are computed from the point-set MBB.

rectangle_heightfloat, default=0

Target rectangle height. Must be provided together with rectangle_width. When both are provided and non-zero, nx and ny are ignored and the grid dimensions are computed from the point-set MBB.

lhfloat, default=10

Hexagon side length when shape=”hexagon”.

realizationsint, default=0

Number of CSR simulations used to compute a Monte Carlo p-value. If 0, no simulation-based inference is performed.

windowshapely geometry, optional

Study window (e.g., Polygon or MultiPolygon). If None, the window is taken to be the axis-aligned MBB rectangle of points.

rngNone | int | numpy.random.Generator | numpy.random.RandomState, optional

Random number generator control for reproducible CSR simulations when realizations > 0.

  • None: create a new numpy.random.default_rng()

  • int: use as a seed for numpy.random.default_rng(seed)

  • Generator: used as-is

  • RandomState: wrapped via numpy.random.default_rng(RandomState)

Attributes:
pointsnumpy.ndarray

(n, 2) array of event coordinates.

mbbnumpy.ndarray

Bounding box of points as [xmin, ymin, xmax, ymax].

windowshapely geometry

Study window used for simulation and plotting.

shapestr

Quadrat tessellation type: “rectangle” or “hexagon”.

rngnumpy.random.Generator

RNG used for CSR simulations (always stored as a Generator).

mrRectangleM or HexagonM

Tessellation manager instance.

cell_idslist of int

Cell identifiers included in the test statistic (all grid cells).

chi2float

Observed Pearson chi-square statistic.

dfint

Degrees of freedom for the analytical chi-square reference distribution, equal to k - 1 where k is the number of included cells.

chi2_pvaluefloat

Analytical p-value from the chi-square distribution.

chi2_contribnumpy.ndarray

Per-cell chi-square contributions aligned with cell_ids, computed as (O - E)^2 / E with E = mean(O) over included cells.

chi2_realizationsnumpy.ndarray

Simulated chi-square statistics for CSR realizations. Present only when realizations > 0.

chi2_r_pvaluefloat

Monte Carlo p-value based on chi2_realizations, computed using the standard +1 correction: ( #{T_sim >= T_obs} + 1 ) / (realizations + 1). Present only when realizations > 0.

See also

RectangleM

Rectangular tessellation over the point-set MBB.

HexagonM

Hexagonal tessellation over the point-set MBB.

Notes

  • The analytical test uses scipy.stats.chisquare with expected counts equal across cells (i.e., E = mean(O)). This corresponds to a homogeneous CSR null with equal-area cells. For irregular windows, a fully-correct analytical reference would area-weight expectations.

  • The simulation-based null generates CSR realizations within window with intensity n / area(window). Reproducibility depends on passing rng through to the underlying CSR generator (poisson(..., rng=...)).

__init__(pp, shape='rectangle', nx=3, ny=3, rectangle_width=0, rectangle_height=0, lh=10, realizations=0, window=None, rng=None)[source]

Methods

__init__(pp[, shape, nx, ny, ...])

plot([title, show])

plot(title='Quadrat Count', show='counts')[source]