GraphBuilder redesign

[jkibele]

Following up on this issue, I've decided I need to redesign the pyriv.graph_prep module and GraphBuilder object a bit. Basically, GraphBuilder needs to be able to handle the following tasks:

1. Network Creation
   1. River Network
      1. Data import (shp or graphpickle for now)
      2. Addition of coastline (to identify river mouths)
      3. Identification of rivermouths and inland deadends
      4. Pruning useless bits off the graph
      5. Fixing unintended breaks
      6. Node coordinate rounding
   2. Coast Network
      1. Options for handling lines or polygons (multipart and single part)
      2. Simplification and node count metrics for prediction of processing time
      3. Edge creation (multiprocessor command line scripts?)
   3. Network Join

In order to do this across all likely scenarios, it has to account for the following cases:

1. When the river mouths connect perfectly to the coastline (simplest)
2. When the river mouths are close enough to be auto completed to the coastline
3. When the connection segments must be created and added in.
4. Any combination of the previous cases.

I think the work-flow needs to looks something like this:

1. Initialize GraphBuilder object with river shp, coastline (polygon) shp, and river_mouth_tolerance value.
2. Get feed back on the inputs with potential problems flagged. Essentially river network dead ends must be categorized:
   • River mouths (connected to coastline)
   • Dead ends:
     • Ocean (river dead ends outside land polygon)
     • Auto complete candidates (river dead end on land, within tolerance from coastline)
     • True dead ends (river dead end on land, beyond tolerance from coastline). These can be unintentional river network breaks or candidates for hand drawn connection to the coastline.
3. Offer functions for:
   • Auto complete
   • Adding in drawn segments
   • Fixing network gaps
4. Export of completed river graph to graph pickle format.
5. Creation and export of coastal network
6. Joining of river and coastal networks allowing for:
   • Ocean nodes
   • Coastal nodes

[jkibele]

So, the RiverGraph object currently includes the coastline because it needs a concept of "river mouth" that is distinct from just a dead end. It might be cleaner to, if possible, use GraphBuilder to generate a RiverGraph that is pruned of any extraneous dead ends. Then RiverGraph could treat all deadends as river mouths in distance calculations.