Update geospatial readme (#4417)

Co-authored-by: Brendan Ward <bcward@astutespruce.com>
Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net>
Co-authored-by: Geoff Boeing <gboeing@users.noreply.github.com>
Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>

Co-authored-by: Brendan Ward <bcward@astutespruce.com>
Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net>
Co-authored-by: Geoff Boeing <gboeing@users.noreply.github.com>
Co-authored-by: Ross Barnowski <rossbar@berkeley.edu>

2 files changed, 69 insertions, 0 deletions

diff --git a/examples/geospatial/README.txt b/examples/geospatial/README.txt
index 57809c61..1631af40 100644
--- a/examples/geospatial/README.txt
+++ b/examples/geospatial/README.txt
@@ -1,2 +1,7 @@
 Geospatial
 ----------
+
+The following geospatial examples showcase different ways of performing
+network analyses using packages within the geospatial Python ecosystem.
+Example spatial files are stored directly in this directory.
+See the `extended description <geospatial/extended_description.html>`_ for more details.
diff --git a/examples/geospatial/extended_description.rst b/examples/geospatial/extended_description.rst
new file mode 100644
index 00000000..6ba1a51e
--- /dev/null
+++ b/examples/geospatial/extended_description.rst
@@ -0,0 +1,64 @@
+:orphan:
+
+Geospatial Examples Description
+-------------------------------
+
+Dependencies
+~~~~~~~~~~~~
+
+`GeoPandas <https://geopandas.readthedocs.io/>`__ provides
+interoperability between geospatial formats and storage mechanisms
+(e.g., databases) and Pandas data frames for tabular-oriented processing
+of spatial data, as well as a wide array of supporting functionality
+including spatial indices, spatial predicates (e.g., test if geometries
+intersect each other), spatial operations (e.g., the area of overlap
+between intersecting polygons), and more.
+
+`PySAL <https://pysal.org/>`__ provides a rich suite of spatial analysis
+algorithms. From a network analysis context, `spatial
+weights <https://pysal.org/libpysal/api.html#spatial-weights>`__
+provide… (Levi please add more here).
+
+See the following examples that use PySAL:
+
+* ``examples/geospatial/plot_delaunay.py``
+* ... (depends on split between PySAL and Momepy examples)
+
+`momepy <http://docs.momepy.org/en/stable/>`__ builds on top of
+GeoPandas and PySAL to provide a suite of algorithms focused on urban
+morphology. From a network analysis context, momepy enables you to
+convert your line geometry to ``networkX.MultiGraph`` and back to 
+``GeoDataFrames`` and apply a range of analytical functions aiming at 
+morphological description of (street) network configurations.
+
+See the following examples that use momepy:
+
+* ...
+
+`OSMnx <https://osmnx.readthedocs.io/>`__ provides a set of tools to retrieve, model, project, analyze, and visualize OpenStreetMap street networks (and any other networked infrastructure) as NetworkX MultiDiGraph objects, and convert these MultiDiGraphs to/from Geopandas GeoDataFrames. It can automatically add node/edge attributes for: elevation and grade (using the Google Maps Elevation API), edge travel speed, edge traversal time, and edge bearing. It can also retrieve any other spatial data from OSM (such as building footprints, public parks, schools, transit stops, etc) as Geopandas GeoDataFrames.
+
+See the following examples that use OSMnx:
+
+* ``examples/geospatial/plot_osmnx.py``
+
+Key Concepts
+~~~~~~~~~~~~
+
+One of the essential tasks in network analysis of geospatial data is
+defining the spatial relationships between spatial features (points,
+lines, or polygons).
+
+``PySAL`` provides several ways of representing these spatial
+relationships between features using the concept of spatial weights.
+These include relationships such as ``Queen``, ``Rook``, ...
+(Levi please add more here with a brief explanation of each).
+
+``momepy`` allows representation of street networks as both primal
+and dual graphs (in a street network analysis sense). The primal approach
+turns intersections into Graph nodes and street segments into edges,
+a format which is used for a majority of morphological studies. The dual 
+approach uses street segments as nodes and intersection topology
+as edges, which allows encoding of angular information (i.e an analysis
+can be weighted by angles between street segments instead of their length).
+
+``OSMnx`` represents street networks as primal, nonplanar, directed graphs with possible self-loops and parallel edges to model real-world street network form and flow. Nodes represent intersections and dead-ends, and edges represent the street segments linking them. Details of OSMnx's modeling methodology are available at https://doi.org/10.1016/j.compenvurbsys.2017.05.004