# pointpats.PoissonClusterPointProcess

class pointpats.PoissonClusterPointProcess(window, n, parents, radius, samples, keep=False, asPP=False, conditioning=False)

  Poisson cluster point process (Neyman Scott). Two stages: 1. parent CSR process: \(N\)-conditioned or \(\lambda\)-conditioned. If parent events follow a \(\lambda\)-conditioned CSR process, the number of parent events varies across realizations. 2. child process: fixed number of points in circle centered on each parent.

  Parameters:
    window `Window`

      Bounding geometric object to contain point process realizations.

    n int

      Size of each realization.

    parents int

      Number of parents.

    radius float

      Radius of the circle centered on each parent.

    samples list

      Number of realizations.

    asPP bool

      Control the data type of value in the “realizations” dictionary. If True, the data type is point pattern as defined in pointpattern.py; if False, the data type is an two-dimensional array.

    conditioning bool

      If True, use the \(lambda\)-conditioned CSR process for parent events, leading to varied number of parent events across realizations; if False, use the \(N\)-conditioned CSR process.

  Examples

      >>> import libpysal as ps
      >>> import numpy as np
      >>> from pointpats import Window
      >>> from libpysal.cg import shapely_ext

  Open the virginia polygon shapefile

      >>> va = ps.io.open(ps.examples.get_path("virginia.shp"))

  Create the exterior polygons for VA from the union of the county shapes

      >>> polys = [shp for shp in va]
      >>> state = shapely_ext.cascaded_union(polys)

  Create window from virginia state boundary

      >>> window = Window(state.parts)

  1. Simulate a Poisson cluster process of size 200 with 10 parents and 20 children within 0.5 units of each parent (parent events: \(N\)-conditioned CSR)

      >>> np.random.seed(10)
      >>> samples1 = PoissonClusterPointProcess(window, 200, 10, 0.5, 1, asPP=True, conditioning=False)
      >>> samples1.parameters # number of events for the realization
      {0: {'n': 200}}
      >>> samples1.num_parents #number of parent events for each realization
      {0: 10}
      >>> samples1.children # number of children events centered on each parent event
      20

  2. Simulate a Poisson cluster process of size 200 with 10 parents and 20 children within 0.5 units of each parent (parent events: \(\lambda\)-conditioned CSR)

      >>> np.random.seed(10)
      >>> samples2 = PoissonClusterPointProcess(window, 200, 10, 0.5, 1, asPP=True, conditioning=True)
      >>> samples2.parameters # number of events for the realization might not be equal to 200
      {0: {'n': 260}}
      >>> samples2.num_parents #number of parent events for each realization
      {0: 13}
      >>> samples2.children # number of children events centered on each parent event
      20

  Attributes:
    children int

      Number of childrens centered on each parent. Can be considered as local intensity.

    num_parents dictionary

      The key is the index of each realization. The value is the number of parent events for each realization.

    realizations dictionary

      The key is the index of each realization, and the value is simulated event points for each realization. The data type of the value is controlled by the parameter “asPP”.

    parameters dictionary

      Dictionary of a dictionary. The key is the index of each realization, and the value is a dictionary with the key ‘n’ and the value always equal to the parameter n in the case of N-conditioned process. For example, {0:{‘n’:100},1:{‘n’:100},2:{‘n’:100}} 2. randomly generated from a Possion process in the case of lambda-conditioned process. For example, {0:{‘n’:97},1:{‘n’:100},2:{‘n’:98}}

  __init__(window, n, parents, radius, samples, keep=False, asPP=False, conditioning=False)

  Methods

  `__init__`(window, n, parents, radius, samples) |
  `draw`(parameter) | Generate a series of point coordinates within the given window.
  `realize`(n) | Generate n points which are distributed in a clustered fashion in the minimum bounding box of "window".
  `setup`() | Generate the number of events for each realization.

  draw(parameter)

    Generate a series of point coordinates within the given window.

    Parameters:
      parameter dictionary

        Key: ‘n’. Value: size of the realization.

    Returns:
      : array

        A series of point coordinates.

  realize(n)

    Generate n points which are distributed in a clustered fashion in the minimum bounding box of “window”.

    Parameters:
      n int

        Number of point events.

    Returns:
      res array

        (n,2), n point coordinates.

  setup()

    Generate the number of events for each realization. If “conditioning” is False, all the event numbers are the same; if it is True, the number of parents is a random variable following a Poisson distribution, resulting in varied number of events.