Edit docs for graph and meta modules

Author: peterrrock2

docs/_static/shipit-squirrel.png

@@ -6,10 +6,15 @@ API Reference
 .. contents:: Table of Contents
     :local:
 
+
+.. Only the graph class in intended to be a part of the public API, so 
+    we only document that here.
+
 Adjacency graphs
 ----------------
 
 .. autoclass:: gerrychain.graph.graph.Graph
+    :members:
 
 Partitions
 ----------
@@ -36,17 +41,6 @@ Binary constraints
 .. automodule:: gerrychain.constraints
     :members:
 
-.. autoclass:: gerrychain.constraints.Validator
-
-.. autoclass:: gerrychain.constraints.UpperBound
-
-.. autoclass:: gerrychain.constraints.LowerBound
-
-.. autoclass:: gerrychain.constraints.SelfConfiguringLowerBound
-
-.. autoclass:: gerrychain.constraints.SelfConfiguringUpperBound
-
-.. autoclass:: gerrychain.constraints.WithinPercentRangeOfBounds
 
 Updaters
 --------

docs/api.rst

@@ -1,3 +1,18 @@
+"""
+This module provides a :class:`~gerrychain.graph.Graph` class that
+extends the :class:`networkx.Graph` and includes some useful methods
+for working with graphs representing geographic data. The class 
+:class:`~gerrychain.graph.Graph` is the only part of this module that
+is intended to be used directly by users of GerryChain.
+
+The other classes and functions in this module are used internally by
+GerryChain. These include the geographic manipulation functions
+available in :mod:`gerrychain.graph.geo`, the adjacency functions
+in :mod:`gerrychain.graph.adjacency`, and the class
+:class:`~gerrychain.graph.FrozenGraph` in the file
+:mod:`gerrychain.graph.graph`. See the documentation at the top
+of those files for more information.
+"""
 from .adjacency import *
 from .geo import *
 from .graph import *

gerrychain/graph/__init__.py

@@ -1,7 +1,20 @@
+"""
+This module provides a set of functions to help determine and
+manipulate the adjacency of geometries within a particular
+graph. The functions in this module are used internally to ensure
+that the geometry data that we are working with is sufficiently
+well-defined to be used for analysis.
+
+Some of the type hints in this module are intentionally left
+unspecified because of import issues.
+"""
+
 import warnings
+from geopandas import GeoDataFrame
+from typing import Dict
 
 
-def neighbors(df, adjacency):
+def neighbors(df: GeoDataFrame, adjacency: str) -> Dict:
     if adjacency not in ("rook", "queen"):
         raise ValueError(
             "The adjacency parameter provided is not supported. "
@@ -12,8 +25,15 @@ def neighbors(df, adjacency):
 
 
 def str_tree(geometries):
-    """Add ids to geometries and create a STR tree for spatial indexing.
+    """
+    Add ids to geometries and create a STR tree for spatial indexing.
     Use this for all spatial operations!
+
+    :param geometries: A Shapely geometry object to construct the tree from.
+    :type geometries: shapely.geometry.BaseGeometry
+
+    :returns: A Sort-Tile-Recursive tree for spatial indexing.
+    :rtype: shapely.strtree.STRtree
     """
     from shapely.strtree import STRtree
 
@@ -25,7 +45,17 @@ def str_tree(geometries):
 
 
 def neighboring_geometries(geometries, tree=None):
-    """Generator yielding tuples of the form (id, (ids of neighbors))."""
+    """
+    Generator yielding tuples of the form (id, (ids of neighbors)).
+
+    :param geometries: A Shapeley geometry object to construct the tree from
+    :type geometries: shapely.geometry.BaseGeometry
+    :param tree: A Sort-Tile-Recursive tree for spatial indexing. Default is None.
+    :type tree: shapely.strtree.STRtree, optional
+
+    :returns: A generator yielding tuples of the form (id, (ids of neighbors))
+    :rtype: Generator
+    """
     if tree is None:
         tree = str_tree(geometries)
 
@@ -40,8 +70,15 @@ def neighboring_geometries(geometries, tree=None):
 
 
 def intersections_with_neighbors(geometries):
-    """Generator yielding tuples of the form (id, {neighbor_id: intersection}).
+    """
+    Generator yielding tuples of the form (id, {neighbor_id: intersection}).
     The intersections may be empty!
+
+    :param geometries: A Shapeley geometry object.
+    :type geometries: shapely.geometry.BaseGeometry
+
+    :returns: A generator yielding tuples of the form (id, {neighbor_id: intersection})
+    :rtype: Generator
     """
     for i, neighbors in neighboring_geometries(geometries):
         intersections = {
@@ -51,6 +88,16 @@ def intersections_with_neighbors(geometries):
 
 
 def warn_for_overlaps(intersection_pairs):
+    """
+    :param intersection_pairs: An iterable of tuples of
+        the form (id, {neighbor_id: intersection})
+    :type intersection_pairs: Iterable
+
+    :returns: A generator yielding tuples of intersection pairs
+    :rtype: Generator
+
+    :raises: UserWarning if there are overlaps among the given polygons
+    """
     overlaps = set()
     for i, intersections in intersection_pairs:
         overlaps.update(
@@ -70,7 +117,13 @@ def warn_for_overlaps(intersection_pairs):
 
 
 def queen(geometries):
-    """Return queen adjacency dictionary for the given collection of polygons."""
+    """
+    :param geometries: A Shapeley geometry object.
+    :type geometries: shapely.geometry.BaseGeometry
+
+    :returns: The queen adjacency dictionary for the given collection of polygons.
+    :rtype: Dict
+    """
     intersection_pairs = warn_for_overlaps(intersections_with_neighbors(geometries))
 
     return {
@@ -84,11 +137,18 @@ def queen(geometries):
 
 
 def rook(geometries):
-    """Return rook adjacency dictionary for the given collection of polygons."""
+    """
+    :param geometries: A Shapeley geometry object.
+    :type geometries: shapely.geometry.BaseGeometry
+
+    :returns: The rook adjacency dictionary for the given collection of polygons.
+    :rtype: Dict
+    """
     return {
         i: {j: data for j, data in neighbors.items() if data["shared_perim"] > 0}
         for i, neighbors in queen(geometries).items()
     }
 
 
+# Dictionary mapping adjacency types to their corresponding functions.
 adjacencies = {"rook": rook, "queen": queen}

gerrychain/graph/adjacency.py

@@ -1,32 +1,61 @@
+"""
+This module contains functions for working with GeoDataFrames and Shapely
+geometries. Specifically, it contains functions for handling and reprojecting
+the Universal Transverse Mercator projection, and for identifying bad geometries
+within a given GeoDataFrame.
+"""
+
 from collections import Counter
 from gerrychain.vendor.utm import from_latlon
+# from shapely.geometry.base import BaseGeometry
+from geopandas import GeoDataFrame
 
 
 def utm_of_point(point):
+    """
+    Given a point, return the Universal Transverse Mercator zone number
+    for that point.
+    """
     return from_latlon(point.y, point.x)[2]
 
 
-def identify_utm_zone(df):
+def identify_utm_zone(df: GeoDataFrame) -> int:
+    """
+    Given a GeoDataFrame, identify the Universal Transverse Mercator zone
+    number for the centroid of the geometries in the dataframe.
+    """
     wgs_df = df.to_crs("+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs")
     utm_counts = Counter(utm_of_point(point) for point in wgs_df["geometry"].centroid)
     # most_common returns a list of tuples, and we want the 0,0th entry
     most_common = utm_counts.most_common(1)[0][0]
     return most_common
 
 
-def explain_validity(geo):
-    """Given a geometry, explain the validity.
+# Explicit type hint intentionally omitted here because of import issues.
+def explain_validity(geo) -> str:
+    """
+    Given a geometry that is shapely interpretable, explain the validity.
     Light wrapper around shapely's explain_validity.
+
+    :param geo: Shapely geometry object
+    :type geo: shapely.geometry.BaseGeometry
+
+    :returns: Explanation for the validity of the geometry
+    :rtype: str
     """
     import shapely.validation
     return shapely.validation.explain_validity(geo)
 
 
 def invalid_geometries(df):
-    """Given a GeoDataFrame, returns a list of row indices
+    """
+    Given a GeoDataFrame, returns a list of row indices
     with invalid geometries.
 
-    :param df: :class:`geopandas.GeoDataFrame`
+    :param df: The GeoDataFrame to examine
+    :type df: :class:`geopandas.GeoDataFrame`
+
+    :returns: List of row indices with invalid geometries
     :rtype: list of int
     """
     invalid = []
@@ -38,9 +67,15 @@ def invalid_geometries(df):
 
 
 def reprojected(df):
-    """Returns a copy of `df`, projected into the coordinate reference system of a suitable
+    """
+    Returns a copy of `df`, projected into the coordinate reference system of a suitable
         `Universal Transverse Mercator`_ zone.
-    :param df: :class:`geopandas.GeoDataFrame`
+
+    :param df: The GeoDataFrame to reproject
+    :type df: :class:`geopandas.GeoDataFrame`
+
+    :returns: A copy of `df`, projected into the coordinate reference system of a suitable
+        UTM zone.
     :rtype: :class:`geopandas.GeoDataFrame`
 
     .. _`Universal Transverse Mercator`: https://en.wikipedia.org/wiki/UTM_coordinate_system