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

  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.

    nx int, default=3

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

    ny int, default=3

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

    rectangle_width float, 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_height float, 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.

    lh float, default=10

      Hexagon side length when shape=”hexagon”.

    realizations int, default=0

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

    window shapely geometry, optional

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

    rng None | 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:
    points numpy.ndarray

      (n, 2) array of event coordinates.

    mbb numpy.ndarray

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

    window shapely geometry

      Study window used for simulation and plotting.

    shape str

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

    rng numpy.random.Generator

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

    mr RectangleM or HexagonM

      Tessellation manager instance.

    cell_ids list of int

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

    chi2 float

      Observed Pearson chi-square statistic.

    df int

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

    chi2_pvalue float

      Analytical p-value from the chi-square distribution.

    chi2_contrib numpy.ndarray

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

    chi2_realizations numpy.ndarray

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

    chi2_r_pvalue float

      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)

  Methods

  `__init__`(pp[, shape, nx, ny, ...]) |
  `plot`([title, show]) |

  plot(title='Quadrat Count', show='counts')