pointpats.ellipse¶

pointpats.ellipse(points, weights=None, method='crimestat', crimestatCorr=True, degfreedCorr=True)[source]¶

pointpats.ellipse(points: ndarray, weights=None, method='crimestat', crimestatCorr=True, degfreedCorr=True) → tuple[float, float, float]

pointpats.ellipse(points: GeoPandasBase, weights=None, method='crimestat', crimestatCorr=True, degfreedCorr=True) → Polygon

Computes a weighted standard deviational ellipse for a set of point geometries.

Parameters:

pointsarray-like: Array representing a point pattern.
weightsarray-like, optional: Array of weights for each point.
methodstr: Correction method to apply. Must be either ‘crimestat’ or ‘yuill’.
crimestatCorrbool: Whether to apply the CrimeStat correction (used only if method == ‘yuill’).
degfreedCorrbool: Whether to apply degrees-of-freedom correction (used only if method == ‘yuill’). Apply degrees-of-freedom correction if method == ‘yuill’.

Returns:

tuple(major_axis_length, minor_axis_length, rotation_angle) | ellipse

Notes

Implements approach from:

https://www.icpsr.umich.edu/CrimeStat/files/CrimeStatChapter.4.pdf

Examples

>>> import numpy as np
>>> import geopandas as gpd

Create an array of point coordinates.

>>> coords = np.array(
...     [
...         [66.22, 32.54],
...         [22.52, 22.39],
...         [31.01, 81.21],
...         [9.47, 31.02],
...         [30.78, 60.10],
...         [75.21, 58.93],
...         [79.26, 7.68],
...         [8.23, 39.93],
...         [98.73, 77.17],
...         [89.78, 42.53],
...         [65.19, 92.08],
...     ]
... )

Passing an array of coordinates returns a tuple capturing the semi-major axis, semi-minor axis and clockwise rotation angle of the ellipse.

>>> ellipse(coords)
(np.float64(50.13029459102783), np.float64(37.95222670267865), np.float64(0.3465582095042642))

Passing a GeoPandas object returns a shapely geometry.

>>> geoms = gpd.GeoSeries.from_xy(*coords.T)
>>> ellipse(geoms)
<POLYGON ((99.55 66.626, 100.586 63.045, 101.159 59.334, 101.262 55.53, 100....>