v.ppa - GRASS manual

NAME

v.ppa - Point pattern analysis using the G, F, K, and L summary functions.

KEYWORDS

vector, statistics, point pattern analysis, parallel

SYNOPSIS

v.ppa

v.ppa --help

v.ppa input=name method=string [output=name] format=name [num_distances=integer] [random_points=integer] [max_distance=float] [correction=string] [seed=integer] [nprocs=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

input=name [required]: Name of input vector map; Or data source for direct OGR access
method=string [required]: Summary function to compute; Options: g, f, k, l; g: Nearest neighbor distance distribution function; f: Empty space function; k: Ripley's K function; l: L function (variance stabilized K function)
output=name: Name for output file; If omitted or '-', the results are printed to standard output
format=name [required]: Output format; Options: plain, csv, json; Default: plain; plain: Human readable text output; csv: CSV (Comma Separated Values); json: JSON (JavaScript Object Notation)
num_distances=integer: Number of distances; Number of equally spaced distances at which the function is estimated; Default: 100
random_points=integer: Number of random points for the F function; Empty space distances are sampled at this many uniformly random locations; Default: 1000
max_distance=float: Maximum distance for the K and L functions; Default is one quarter of the shorter side of the computational region
correction=string: Edge correction for the K and L functions; Options: isotropic, none; Default: isotropic; isotropic: Ripley's isotropic edge correction; none: No edge correction
seed=integer: Seed value for the random number generator; Used for the random locations of the F function
nprocs=integer: Number of threads for parallel computing; 0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs; Default: 0

DESCRIPTION
NOTES
EXAMPLES
TODO
REFERENCES
SEE ALSO
AUTHORS

DESCRIPTION

v.ppa performs point pattern analysis on the points of a vector map using one of four summary functions: the nearest neighbor distance distribution function G, the empty space function F, Ripley's K function, and the variance stabilized L function. The functions describe whether and at which spatial scales a point pattern is clustered, random, or dispersed.

The method option selects the summary function:

g: the fraction of points whose nearest neighbor lies within distance d, estimated for a range of distances.
f: the fraction of uniformly random locations whose nearest pattern point lies within distance d. The number of sampled locations is set by random_points.
k: the average number of further points within distance d of a typical point, scaled by the intensity. Under complete spatial randomness (CSR), K(d) equals pi * d^2.
l: the transformation L(d) = sqrt(K(d) / pi), which equals d under CSR and stabilizes the variance of K.

Each estimate is evaluated at num_distances equally spaced distances and reported together with the theoretical value of the function under CSR, so the output can be plotted and interpreted directly. Values above the CSR reference indicate clustering, values below it indicate dispersion (for F, the interpretation is reversed).

Clustered, random, and dispersed point patterns
Figure: Clustered, random (CSR), and dispersed point patterns of about 200 points in a 1000x1000 window, used in the figures below.

G function for the three patterns
Figure: G function. Clustered patterns rise left of the CSR expectation because nearest neighbors are close; dispersed patterns stay at zero up to their minimum spacing and then rise right of it.

F function for the three patterns
Figure: F function. The interpretation is reversed compared to G: dispersed patterns rise faster than the CSR expectation, clustered patterns slower because of their large empty spaces.

Ripley's K function for the three patterns
Figure: Ripley's K function with isotropic edge correction. Clustered patterns lie above the CSR expectation, dispersed patterns below it up to the pattern spacing.

L function for the three patterns
Figure: L function. The square root transformation makes departures from CSR easier to see than in K.

The computational region is the observation window of the analysis: it defines the area used to estimate the intensity (points per unit area), the sampling window of the F function, the edge correction geometry, and the default distance range. Points of the input map that fall outside the current region are ignored with a warning. Use g.region to set the study area before running the tool.

Results are printed to standard output by default, or written to the file given by output. The format option selects human readable text (plain), comma separated values (csv), or JSON (json). The JSON output includes the number of points, the estimated intensity, the observation window, and, for K and L, the edge correction, followed by the per-distance results.

NOTES

The K and L functions apply Ripley's isotropic edge correction by default: each point pair is weighted by the reciprocal of the fraction of the circle through the neighbor, centered at the point, that lies inside the window. Without a correction (correction=none), K and L are biased downward at larger distances because part of each circle falls outside the observed window. The G and F estimates are currently uncorrected empirical distribution functions; interpret them against the reported CSR reference rather than in absolute terms.

The K and L functions are evaluated up to max_distance, which defaults to one quarter of the shorter side of the computational region, a common rule of thumb beyond which K estimates become unreliable. The G and F functions are evaluated up to the largest observed nearest neighbor or empty space distance, so their last value is always 1.

The intensity is estimated as the number of points inside the region divided by the region area. Duplicate point locations are retained and count as nearest neighbors at distance zero. Only point geometry is used; for 3D maps the z coordinate is ignored.

The seed option only affects the F function, which samples random locations; G, K, and L are deterministic. The computation of all functions is parallelized with OpenMP; the number of threads is set with nprocs.

EXAMPLES

Generate a random point pattern in a 1000 by 1000 window and compare its K function against CSR (the two columns should be similar):

g.region n=1000 s=0 w=0 e=1000 res=1
v.random output=random_points npoints=500 seed=42
v.ppa input=random_points method=k format=csv

Estimate the G function of a point map within the current region and save it to a file:

v.ppa input=points_of_interest method=g format=csv output=g_function.csv

Compute the L function without edge correction at 200 distances up to 500 map units:

v.ppa input=points_of_interest method=l correction=none \
    num_distances=200 max_distance=500

Read the K function results into Python:

from grass.tools import Tools

tools = Tools()
data = tools.v_ppa(input="random_points", method="k", format="json").json
print(data["intensity"], data["results"][0])

TODO

Monte Carlo simulation envelopes for testing deviations from CSR.
Bivariate (cross-type) K function.
Border corrections for the G and F functions.

REFERENCES

Ripley, B.D. (1977). Modelling spatial patterns. Journal of the Royal Statistical Society, Series B 39, 172-212.
Baddeley, A., Rubak, E., Turner, R. (2015). Spatial Point Patterns: Methodology and Applications with R. Chapman and Hall/CRC.

AUTHORS

Corey T. White, OpenPlains Inc. and Center for Geospatial Analytics, NC State University

SOURCE CODE

Available at: v.ppa source code (history)

Latest change: Tuesday Aug 25 05:07:36 2026 in commit: f5ebd74c5cf2a1c1fdeeee2c5cfa7702f7fdc2e1