# pointpats.ellipse

pointpats.ellipse(points, weights=None, method='crimestat', crimestatCorr=True, degfreedCorr=True)
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:
    points array-like

      Array representing a point pattern.

    weights array-like, optional

      Array of weights for each point.

    method str

      Correction method to apply. Must be either ‘crimestat’ or ‘yuill’.

    crimestatCorr bool

      Whether to apply the CrimeStat correction (used only if method == ‘yuill’).

    degfreedCorr bool

      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....>