# pointpats.PointPattern

class pointpats.PointPattern(points, window=None, names=None, coord_names=None)

  Planar Point Pattern Class 2-D.

  Parameters:
    points: array

      (n,p), n points with p >= 2 attributes on each point. Two attributes must comprise the spatial coordinate pair. Default is that the first two attributes are the x and y spatial coordinates.

    window: :class:`.Window`

      Bounding geometric object for the point pattern. If not specified, window will be set to the minimum bounding rectangle of the point pattern.

    names: list

      The names of the attributes.

    coord_names: list

      The names of the attributes defining the two spatial coordinates.

  Examples

      >>> from pointpats import PointPattern
      >>> points = [[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], [54.46, 8.48]]
      >>> pp = PointPattern(points)
      >>> pp.n
      12
      >>> pp.mean_nnd
      21.612139802089246
      >>> pp.lambda_mbb
      0.0015710507711240867
      >>> pp.lambda_hull
      0.0022667153468973137
      >>> pp.hull_area
      5294.00395
      >>> pp.mbb_area
      7638.200000000001

  __init__(points, window=None, names=None, coord_names=None)

  Methods

  `__init__`(points[, window, names, coord_names]) |
  `add_marks`(marks[, mark_names]) |
  `explode`(mark) | Explode a marked point pattern into a sequence of individual point patterns.
  `find_pairs`(r) | Find all pairs of points in the pattern that are within r units of each other
  `flip_coordinates`() | Flips the coordinates of a point pattern.
  `get_window`() | Bounding geometry for the point pattern
  `knn`([k]) | Find k nearest neighbors for each point in the pattern
  `knn_other`(other[, k]) | Find k nearest neighbors in the pattern for each point in other
  `plot`([window, title, hull, get_ax]) | Plot function for a point pattern.
  `set_window`(window) |
  `summary`() | Description of the point pattern.
  `superimpose`(point_pattern) | Returns a superimposed point pattern.
  `unique`() | Remove duplicate points in the point pattern.

  Attributes

  `hull` | Points defining convex hull in counterclockwise order
  `hull_area` | Area of convex hull
  `lambda_hull` | Intensity based on convex hull
  `lambda_mbb` | Intensity based on minimum bounding box
  `lambda_window` | Intensity estimate based on area of window
  `max_nnd` | Max nearest neighbor distance
  `mbb` | Minimum bounding box
  `mbb_area` | Area of minimum bounding box
  `mean_nnd` | Mean nearest neighbor distance
  `min_nnd` | Min nearest neighbor distance
  `n` | Number of points
  `nnd` | Nearest neighbor distances
  `rot` | Ripley's rule of thumb for distance range in plotting k and related functions
  `tree` |
  `window` | Bounding geometry for the point pattern

  add_marks(marks, mark_names=None)
  explode(mark)

    Explode a marked point pattern into a sequence of individual point patterns. If the mark has k unique values, then the sequence will be of length k.

    Parameters:
      mark: string

        The label of the mark to use for the subsetting

    Returns:
      pps: list

        sequence of `PointPattern` instances

  find_pairs(r)

    Find all pairs of points in the pattern that are within r units of each other

    Parameters:
      r: float

        diameter of pair circle

    Returns:
      s: set

        pairs of points within r units of each other

  flip_coordinates()

    Flips the coordinates of a point pattern.

    Doesn’t change the structure of data frame. This function swaps _x and _y variables, which are used to represent coordinates.

  get_window()

    Bounding geometry for the point pattern

    `window.Window`

  property hull

    Points defining convex hull in counterclockwise order

  property hull_area

    Area of convex hull

  knn(k=1)

    Find k nearest neighbors for each point in the pattern

    Parameters:
      k: int

        number of nearest neighbors to find

    Returns:
      nn: array (n x k)

        row i column j contains the id for i’s jth nearest neighbor

      nnd: array(n x k)

        row i column j contains the distance between i and its jth nearest neighbor

  knn_other(other, k=1)

    Find k nearest neighbors in the pattern for each point in other

    Parameters:
      other: PointPattern

        `pointpats.PointPattern`

      k: int

        number of nearest neighbors to find

    Returns:
      nn: array (n x k)

        row i column j contains the id for i’s jth nearest neighbor

      nnd: array(n x k)

        row i column j contains the distance between i and its jth nearest neighbor

  property lambda_hull

    Intensity based on convex hull

  property lambda_mbb

    Intensity based on minimum bounding box

  property lambda_window

    Intensity estimate based on area of window

    The intensity of a point process at point \(s_j\) can be defined as:

    \[\lambda(s_j) = \lim \limits_{|\mathbf{A}s_j| \to 0} \left \{ \frac{E(Y(\mathbf{A}s_j)}{|\mathbf{A}s_j|} \right \}\]

    where \(\mathbf{A}s_j\) is a small region surrounding location \(s_j\) with area \(|\mathbf{A}s_j|\), and \(E(Y(\mathbf{A}s_j))\) is the expected number of event points in \(\mathbf{A}s_j\).

    The intensity is the mean number of event points per unit of area at point \(s_j\).

  property max_nnd

    Max nearest neighbor distance

  property mbb

    Minimum bounding box

  property mbb_area

    Area of minimum bounding box

  property mean_nnd

    Mean nearest neighbor distance

  property min_nnd

    Min nearest neighbor distance

  property n

    Number of points

  property nnd

    Nearest neighbor distances

  plot(window=False, title='Point Pattern', hull=False, get_ax=False)

    Plot function for a point pattern.

    Parameters:
      window boolean

        If window is True, plot window of the point pattern. If not, don’t plot window.

      title string

        Name of the figure.

      hull boolean

        If hull is True, plot convex hull of the point pattern. If not, don’t plot convex hull.

      get_ax boolean

        If get_ax is True, return the current plot ax.

    Returns:
      ax matplotlib.axes._subplots.AxesSubplot

        Current plot ax. Only return it when get_ax is True.

  property rot

    Ripley’s rule of thumb for distance range in plotting k and related functions

    One-quarter the smallest side of the mbb.

  set_window(window)
  summary()

    Description of the point pattern.

  superimpose(point_pattern)

    Returns a superimposed point pattern.

    Parameters:
      point_pattern:

        `PointPattern` instance

    Returns:
      superimposed

        `PointPattern` instance

    Examples

        >>> from pointpats import PointPattern
        >>> points1 = [[1, 3], [4, 5], [0, 0]]
        >>> points2 = [[5, 6], [1, 4], [0, 0]]
        >>> pp1 = PointPattern(points1)
        >>> pp2 = PointPattern(points2)
        >>> pp1.superimpose(pp2).points
           x  y
        0  1  3
        1  4  5
        2  0  0
        0  5  6
        1  1  4

  property tree
  unique()

    Remove duplicate points in the point pattern.

    Two points in a point pattern are deemed to be identical if their coordinates are the same, and their marks are the same (if any)

    Returns:
      pp: list

        A deduplicated `PointPattern` instance

    Examples

        >>> from pointpats import PointPattern
        >>> points = [[1.2, 2.1], [1.2, 2.1], [0, 1], [1, 2]]
        >>> pp = PointPattern(points)
        >>> pp.unique().df
             x    y
        0  1.2  2.1
        2  0.0  1.0
        3  1.0  2.0

  property window

    Bounding geometry for the point pattern

    `window.Window`