upxo.geoEntities.point_processes module

Point Process Generation Module

Generate synthetic point patterns for microstructure modeling and testing.

Includes:

  • Poisson (uniform random)

  • Poisson cluster process

  • Matérn hard-core process

  • Regular lattice

  • Gibbs processes

  • Strauss process

  • Log-Gaussian Cox process (LGCP)

  • Thomas cluster process

Example

from upxo.pxtalops.point_processes import PoissonPointProcess, MaternHardCore

# Generate Poisson points ppp = PoissonPointProcess(intensity=0.01, window=(100, 100)) points = ppp.generate()

# Generate hard-core process mhc = MaternHardCore(intensity=0.005, hard_core_radius=5, window=(100, 100)) points = mhc.generate()

class upxo.geoEntities.point_processes.Window(xmin: float = 0.0, xmax: float = 100.0, ymin: float = 0.0, ymax: float = 100.0)[source]

Bases: object

Spatial rectangular window for point-process generation.

xmin, xmax, ymin, ymax

Coordinate bounds of the rectangular sampling domain.

Type:

float

xmin: float = 0.0
xmax: float = 100.0
ymin: float = 0.0
ymax: float = 100.0
property width: float

Width of the bounding window.

Returns:

xmax - xmin.

Return type:

float

property height: float

Height of the bounding window.

Returns:

ymax - ymin.

Return type:

float

property area: float

Area of the bounding window.

Returns:

Product of width and height.

Return type:

float

classmethod from_tuple(bounds: Tuple[float, float, float, float])[source]

Create a window from tuple bounds.

Parameters:

bounds (tuple of float) – Bounds in (xmin, xmax, ymin, ymax) order.

Returns:

Rectangular sampling window.

Return type:

Window

class upxo.geoEntities.point_processes.PointProcess(window: Tuple[float, float, float, float] | None = None, seed: int | None = None)[source]

Bases: ABC

Abstract base class for point processes.

Notes

Subclasses implement generate and return point coordinates as a pandas.DataFrame.

abstractmethod generate() → pandas.DataFrame[source]

Generate a point pattern.

Returns:

Point coordinates with at least x and y columns.

Return type:

pandas.DataFrame

calculate_k_function(points: pandas.DataFrame, r_max: float = 10.0, r_count: int = 50) → Dict[str, numpy.ndarray][source]

Calculates Ripley’s K-function K(r) using PySAL’s pointpats.K.

Parameters:

  • points (pandas.DataFrame) – Point coordinates with x and y columns.

  • r_max (float, optional) – Maximum support radius.

  • r_count (int, optional) – Number of support radii requested by the caller.

Returns:

Dictionary containing support radii under 'r' and K-function values under 'K_r'.

Return type:

dict

calculate_g_r(points: pandas.DataFrame, r_max: float = 10.0, r_count: int = 50, dimension: int = 2) → Dict[str, numpy.ndarray][source]

Calculates the Pair Correlation Function g(r) by deriving it numerically from the K-function obtained via pointpats.K.

Parameters:

  • points (pandas.DataFrame) – DataFrame with x and y columns, and optionally z for 3D workflows.

  • r_max (float, optional) – Maximum radius for the calculation.

  • r_count (int, optional) – Number of radii to sample between zero and r_max.

  • dimension (int, optional) – Spatial dimension of the pattern. Supported values are 2 and 3.

Returns:

Dictionary containing 'r_g' radii and 'g_r' pair correlation estimates.

Return type:

dict

Raises:

ValueError – If dimension is not 2 or 3.

plot(points: pandas.DataFrame, title: str = 'Point Pattern', ax=None)[source]

Plot generated points.

Parameters:

  • points (pandas.DataFrame) – Point coordinates with x and y columns.

  • title (str, optional) – Plot title.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot into. If None, a new figure and axes are created.

Returns:

Axes containing the point pattern plot.

Return type:

matplotlib.axes.Axes

class upxo.geoEntities.point_processes.PoissonPointProcess(intensity: float = 0.01, window: Tuple | None = None, seed: int | None = None)[source]

Bases: PointProcess

Homogeneous Poisson point process.

Points are uniformly distributed; counts follow Poisson distribution.

Parameters:

  • intensity (float, optional) – Mean number of points per unit area.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • seed (int, optional) – Random seed for reproducibility.

generate() → pandas.DataFrame[source]

Generate homogeneous Poisson points.

Returns:

Generated point coordinates with x and y columns.

Return type:

pandas.DataFrame

class upxo.geoEntities.point_processes.InhomogeneousPoissonPointProcess(intensity_func, max_intensity: float, window: Tuple | None = None, seed: int | None = None)[source]

Bases: PointProcess

Inhomogeneous Poisson point process with spatially varying intensity.

Parameters:

  • intensity_func (callable) – Callable accepting x and y arrays and returning local intensity values.

  • max_intensity (float) – Upper bound intensity used for thinning.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • seed (int, optional) – Random seed for reproducibility.

generate() → pandas.DataFrame[source]

Generate an inhomogeneous Poisson process by thinning.

Returns:

Accepted point coordinates with x and y columns.

Return type:

pandas.DataFrame

class upxo.geoEntities.point_processes.PoissonClusterProcess(parent_intensity: float = 0.005, n_offspring_per_parent: int = 10, offspring_radius: float = 5.0, window: Tuple | None = None, seed: int | None = None)[source]

Bases: PointProcess

Poisson cluster process (Neyman-Scott).

Parents follow Poisson; offspring cluster around parents.

Parameters:

  • parent_intensity (float, optional) – Intensity of the parent Poisson process.

  • n_offspring_per_parent (int, optional) – Mean number of offspring per parent.

  • offspring_radius (float, optional) – Standard deviation of offspring displacement around each parent.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • seed (int, optional) – Random seed for reproducibility.

generate() → pandas.DataFrame[source]

Generate clustered offspring points.

Returns:

Generated offspring coordinates with x and y columns.

Return type:

pandas.DataFrame

class upxo.geoEntities.point_processes.MaternHardCore(intensity: float = 0.005, hard_core_radius: float = 5.0, window: Tuple | None = None, seed: int | None = None)[source]

Bases: PointProcess

Matérn hard-core process.

Points repel each other: no two points within hard_core_radius. Generated via thinning of Poisson.

Parameters:

  • intensity (float, optional) – Target candidate intensity. Achieved intensity may be lower after hard-core rejection.

  • hard_core_radius (float, optional) – Minimum allowed distance between accepted points.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • seed (int, optional) – Random seed for reproducibility.

upxo.geoEntities.point_processes.generate(self) → pandas.DataFrame[source]

Generate hard-core points by rejection sampling.

Returns:

Accepted point coordinates with x and y columns.

Return type:

pandas.DataFrame

Notes

Candidate acceptance uses a KDTree nearest-neighbor check against already accepted points.

class upxo.geoEntities.point_processes.ThomasClusterProcess(parent_intensity: float = 0.001, mean_offspring: float = 25, offspring_std: float = 3.0, window: Tuple | None = None, seed: int | None = None)[source]

Bases: PointProcess

Thomas cluster process.

Offspring distributed normally around parent locations. Special case of Neyman-Scott.

Parameters:

  • parent_intensity (float, optional) – Intensity of the parent Poisson process.

  • mean_offspring (float, optional) – Mean number of offspring per parent.

  • offspring_std (float, optional) – Standard deviation of offspring displacement.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • seed (int, optional) – Random seed for reproducibility.

generate() → pandas.DataFrame[source]

Generate Thomas cluster points.

Returns:

Generated offspring coordinates with x and y columns.

Return type:

pandas.DataFrame

class upxo.geoEntities.point_processes.StraussProcess(beta: float = 0.05, gamma: float = 0.5, interaction_range: float = 10.0, window: Tuple | None = None, seed: int | None = None, max_iterations: int = 1000)[source]

Bases: PointProcess

Strauss process: pair-interaction point process.

Inhibitory: points less likely to appear near existing points. Interaction range and strength parameterized.

Parameters:

  • beta (float, optional) – Intensity parameter.

  • gamma (float, optional) – Interaction parameter. Values between 0 and 1 produce inhibition.

  • interaction_range (float, optional) – Radius within which pair interaction is counted.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • seed (int, optional) – Random seed for reproducibility.

  • max_iterations (int, optional) – Number of MCMC proposal iterations.

generate() → pandas.DataFrame[source]

Generate Strauss points by MCMC proposal sampling.

Returns:

Generated point coordinates with x and y columns.

Return type:

pandas.DataFrame

class upxo.geoEntities.point_processes.RegularLattice(spacing: float = 10.0, window: Tuple | None = None, jitter: float = 0.0)[source]

Bases: PointProcess

Regular lattice (grid) of points.

Parameters:

  • spacing (float, optional) – Distance between neighboring grid points.

  • window (tuple or Window, optional) – Spatial sampling bounds.

  • jitter (float, optional) – Standard deviation of Gaussian coordinate perturbation. A value of zero disables jitter.

generate() → pandas.DataFrame[source]

Generate regular lattice points.

Returns:

Lattice point coordinates with x and y columns.

Return type:

pandas.DataFrame

upxo.geoEntities.point_processes.compare_processes(window: Tuple = (0, 100, 0, 100), seed: int = 42)[source]

Generate and plot a comparison of different point processes.

Parameters:

  • window (tuple, optional) – Spatial bounds in (xmin, xmax, ymin, ymax) order.

  • seed (int, optional) – Random seed used for stochastic processes.

Returns:

Figure containing process comparison subplots.

Return type:

matplotlib.figure.Figure