pygeostats.point_patterns¶

Point pattern analysis tools.

f_function ¶

f_function(coords: ndarray, radii: ndarray, bounds: Tuple[float, float, float, float], n_random: int = 2000, random_state: Optional[int] = None) -> np.ndarray

Estimate empty-space CDF F(r) via random probe points.

g_function ¶

g_function(coords: ndarray, radii: ndarray) -> np.ndarray

Estimate nearest-neighbor CDF G(r).

nearest_neighbor_distances ¶

nearest_neighbor_distances(coords: ndarray, k: int = 1, return_indices: bool = False) -> np.ndarray | Tuple[np.ndarray, np.ndarray]

Compute distance to the k-th nearest neighbor for each point.

pair_correlation_function ¶

pair_correlation_function(coords: ndarray, radii: ndarray, area: Optional[float] = None) -> Dict[str, np.ndarray]

Estimate pair correlation g(r) from finite differences of K(r).

ripley_k_function ¶

ripley_k_function(coords: ndarray, radii: ndarray, area: Optional[float] = None) -> np.ndarray

Estimate Ripley's K function (without edge correction).

Notes

This implementation is intended as a baseline and does not include edge correction terms.

ripley_l_function ¶

ripley_l_function(coords: ndarray, radii: ndarray, area: Optional[float] = None) -> np.ndarray

Estimate Ripley's L function from Ripley's K.

cluster_validation_metrics ¶

cluster_validation_metrics(coords: ndarray, labels: ndarray) -> Dict[str, float]

Compute clustering quality metrics for non-noise clusters.

Returns NaN metrics when fewer than two clusters are present.

getis_ord_gi_star ¶

getis_ord_gi_star(coords: ndarray, values: ndarray, distance_threshold: float, include_self: bool = True) -> np.ndarray

Compute local Getis-Ord Gi* z-scores using binary distance weights.

Notes

This implementation uses a fixed distance band and does not apply multiple-testing corrections.

kernel_density_estimate ¶

kernel_density_estimate(coords: ndarray, bandwidth: Optional[float] = None, grid_size: int = 100, bounds: Optional[Tuple[float, float, float, float]] = None) -> Dict[str, np.ndarray]

Estimate spatial intensity surface with Gaussian KDE on a regular grid.

spatial_dbscan ¶

spatial_dbscan(coords: ndarray, eps: float, min_samples: int = 5) -> np.ndarray

Run DBSCAN on spatial coordinates and return cluster labels.

simulate_cox_process ¶

simulate_cox_process(mean_intensity: float, bounds: Tuple[float, float, float, float] = (0.0, 1.0, 0.0, 1.0), grid_size: int = 50, field_sigma: float = 1.0, field_smoothness: float = 2.0, random_state: Optional[int] = None, return_intensity: bool = False) -> np.ndarray | Dict[str, np.ndarray]

Simulate a simple log-Gaussian Cox process on a regular grid.

Parameters:

Name	Type	Description	Default
`mean_intensity`	`float`	Target average intensity per unit area.	required
`bounds`	`tuple of float`	(xmin, xmax, ymin, ymax) simulation window.	`(0.0, 1.0, 0.0, 1.0)`
`grid_size`	`int`	Number of cells per axis used for latent field simulation.	`50`
`field_sigma`	`float`	Standard deviation of latent Gaussian field.	`1.0`
`field_smoothness`	`float`	Gaussian filter sigma (in grid cells) controlling spatial correlation.	`2.0`
`random_state`	`int`	Seed for reproducible simulations.	`None`
`return_intensity`	`bool`	If True, return a dictionary with points and intensity surface.	`False`

simulate_marked_poisson_process ¶

simulate_marked_poisson_process(intensity: float, marks: ndarray | Tuple[str, ...] | Tuple[int, ...] = ('A', 'B'), mark_probabilities: Optional[ndarray] = None, bounds: Tuple[float, float, float, float] = (0.0, 1.0, 0.0, 1.0), random_state: Optional[int] = None) -> Dict[str, np.ndarray]

Simulate a homogeneous marked Poisson point process.

Parameters:

Name	Type	Description	Default
`intensity`	`float`	Event intensity per unit area.	required
`marks`	`array - like`	Available mark categories.	`('A', 'B')`
`mark_probabilities`	`array - like`	Probabilities for mark categories. If None, uses uniform probabilities.	`None`
`bounds`	`tuple of float`	(xmin, xmax, ymin, ymax) simulation window.	`(0.0, 1.0, 0.0, 1.0)`
`random_state`	`int`	Seed for reproducible simulations.	`None`

simulate_poisson_process ¶

simulate_poisson_process(intensity: float, bounds: Tuple[float, float, float, float] = (0.0, 1.0, 0.0, 1.0), random_state: Optional[int] = None) -> np.ndarray

Simulate a homogeneous 2D Poisson point process.

Parameters:

Name	Type	Description	Default
`intensity`	`float`	Event intensity per unit area (lambda).	required
`bounds`	`tuple of float`	(xmin, xmax, ymin, ymax) simulation window.	`(0.0, 1.0, 0.0, 1.0)`
`random_state`	`int`	Seed for reproducible simulations.	`None`

Returns:

Type	Description
`(ndarray, shape(n_points, 2))`	Simulated point coordinates.

compute_spatial_segregation_indices ¶

compute_spatial_segregation_indices(coords: ndarray, marks: ndarray, n_cells: int = 10, bounds: Optional[Tuple[float, float, float, float]] = None) -> Dict[str, float]

Compute baseline spatial segregation metrics over a regular grid.

Returns:

Type	Description
`dict`	`entropy_segregation` : Theil H in [0, 1] (or 0 when undefined). `mean_cell_entropy` : Weighted mean local entropy. `global_entropy` : Entropy of global mark proportions. `dissimilarity_index` : Binary dissimilarity index in [0, 1], NaN if >2 groups. `n_groups` : Number of unique mark groups.