# libpysal.cg.Grid

class libpysal.cg.Grid(bounds, resolution)

  Representation of a binning data structure.

  __init__(bounds, resolution)

    Returns a grid with specified properties.

    __init__(Rectangle, number) -> Grid

    Parameters:
      bounds `the` `area` `for` `the` `grid` `to` `encompass`
      resolution `the` `diameter` `of` `each` `bin`

    Examples

    TODO: complete this doctest >>> g = Grid(Rectangle(0, 0, 10, 10), 1)

  Methods

  `__init__`(bounds, resolution) | Returns a grid with specified properties.
  `add`(item, pt) | Adds an item to the grid at a specified location.
  `bounds`(bounds) | Returns a list of items found in the grid within the bounds specified.
  `in_grid`(loc) | Returns whether a 2-tuple location _loc_ lies inside the grid bounds.
  `nearest`(pt) | Returns the nearest item to a point.
  `proximity`(pt, r) | Returns a list of items found in the grid within a specified distance of a point.
  `remove`(item, pt) | Removes an item from the grid at a specified location.

  add(item, pt)

    Adds an item to the grid at a specified location.

    add(x, Point) -> x

    Parameters:
      item `the` `item` `to` `insert` `into` `the` `grid`
      pt `the` `location` `to` `insert` `the` `item` `at`

    Examples

        >>> g = Grid(Rectangle(0, 0, 10, 10), 1)
        >>> g.add('A', Point((4.2, 8.7)))
        'A'

  bounds(bounds)

    Returns a list of items found in the grid within the bounds specified.

    bounds(Rectangle) -> x list

    Parameters:
      item `the` `item` `to` `remove` `from` `the` `grid`
      pt `the` `location` `the` `item` `was` `added` `at`

    Examples

        >>> g = Grid(Rectangle(0, 0, 10, 10), 1)
        >>> g.add('A', Point((1.0, 1.0)))
        'A'
        >>> g.add('B', Point((4.0, 4.0)))
        'B'
        >>> g.bounds(Rectangle(0, 0, 3, 3))
        ['A']
        >>> g.bounds(Rectangle(2, 2, 5, 5))
        ['B']
        >>> sorted(g.bounds(Rectangle(0, 0, 5, 5)))
        ['A', 'B']

  in_grid(loc)

    Returns whether a 2-tuple location _loc_ lies inside the grid bounds.

    Test tag: <tc>#is#Grid.in_grid</tc>

  nearest(pt)

    Returns the nearest item to a point.

    nearest(Point) -> x

    Parameters:
      pt `the` `location` `to` `search` `near`

    Examples

        >>> g = Grid(Rectangle(0, 0, 10, 10), 1)
        >>> g.add('A', Point((1.0, 1.0)))
        'A'
        >>> g.add('B', Point((4.0, 4.0)))
        'B'
        >>> g.nearest(Point((2.0, 1.0)))
        'A'
        >>> g.nearest(Point((7.0, 5.0)))
        'B'

  proximity(pt, r)

    Returns a list of items found in the grid within a specified distance of a point.

    proximity(Point, number) -> x list

    Parameters:
      pt `the` `location` `to` `search` `around`
      r `the` `distance` `to` `search` `around` `the` `point`

    Examples

        >>> g = Grid(Rectangle(0, 0, 10, 10), 1)
        >>> g.add('A', Point((1.0, 1.0)))
        'A'
        >>> g.add('B', Point((4.0, 4.0)))
        'B'
        >>> g.proximity(Point((2.0, 1.0)), 2)
        ['A']
        >>> g.proximity(Point((6.0, 5.0)), 3.0)
        ['B']
        >>> sorted(g.proximity(Point((4.0, 1.0)), 4.0))
        ['A', 'B']

  remove(item, pt)

    Removes an item from the grid at a specified location.

    remove(x, Point) -> x

    Parameters:
      item `the` `item` `to` `remove` `from` `the` `grid`
      pt `the` `location` `the` `item` `was` `added` `at`

    Examples

        >>> g = Grid(Rectangle(0, 0, 10, 10), 1)
        >>> g.add('A', Point((4.2, 8.7)))
        'A'
        >>> g.remove('A', Point((4.2, 8.7)))
        'A'