Contiguity weight docs

[dfolch]

An undocumented (and useful) feature of the Rook and Queen contiguity weights constructors is that passing in points results in the construction of voronoi polygons, which are then used to build contiguity weights. The current docs imply that only polygons can be passed. You need to read the source code to understand how points result in the identification of contiguous neighbors. I propose modifying the Rook and Queen docs to say something like.

class Rook(W):
    """
    Construct a weights object based on polygons that
    that share at least one edge. A collection of pysal
    polygons can be passed in; passing pysal points
    results in voronoi polygons being built first.

    Parameters
    ----------
    polygons    : list
                a collection of PySAL polygons to build weights from 
                (a collection of points results in the construction of
                voronoi polygons)

[martinfleis]

To be fair, I don't think this behaviour should exist in the first place. Contiguity based on Voronoi polygons around points is not a Queen or Rook contiguity of point geometry. There's an explicit libpysal.weights.Voronoi constructor for that purpose. This is also the reason why we did not mirror this behaviour in Graph.build_contiguity.

[knaaptime]

i dont have a strong opinion about updating the docstring, but in general its a good idea to think of W as deprecated (even if it hasnt been, formally) and start using Graph whenever possible

also, we're not constructing the W from 'PySAL polygons', so the doc would need a bit more love anyway :P

[martinfleis]

@knaaptime That's correct for the vanilla __init__, no? You just always call the data frame constructor.

[knaaptime]

probably, i just figured all the bespoke geometry stuff was gone by this point