adding docs for nX_remove_dangling_nodes and nX_consolidate

benchmark-urbanism · Apr 2, 2019 · ea275c0 · ea275c0
1 parent 1659c8a
commit ea275c0
Show file tree

Hide file tree

Showing 19 changed files with 163 additions and 22 deletions.
diff --git a/docs/images/plots/assignment.png b/docs/images/plots/assignment.png
diff --git a/docs/images/plots/assignment_decomposed.png b/docs/images/plots/assignment_decomposed.png
diff --git a/docs/images/plots/assignment_plot.png b/docs/images/plots/assignment_plot.png
diff --git a/docs/images/plots/graph.png b/docs/images/plots/graph.png
diff --git a/docs/images/plots/graph_after.png b/docs/images/plots/graph_after.png
diff --git a/docs/images/plots/graph_before.png b/docs/images/plots/graph_before.png
diff --git a/docs/images/plots/graph_colour.png b/docs/images/plots/graph_colour.png
diff --git a/docs/images/plots/graph_decomposed.png b/docs/images/plots/graph_decomposed.png
diff --git a/docs/images/plots/graph_dual.png b/docs/images/plots/graph_dual.png
diff --git a/docs/images/plots/graph_example.png b/docs/images/plots/graph_example.png
diff --git a/docs/images/plots/graph_simple.png b/docs/images/plots/graph_simple.png
diff --git a/docs/images/plots/intro_gravity.png b/docs/images/plots/intro_gravity.png
diff --git a/docs/images/plots/intro_mixed_uses.png b/docs/images/plots/intro_mixed_uses.png
diff --git a/docs/images/plots/plots.py b/docs/images/plots/plots.py
@@ -15,7 +15,7 @@
 #
 # INTRO PLOT
 G = mock.mock_graph()
-plot.plot_nX(G, path='graph.png', labels=True)
+plot.plot_nX(G, path='graph.png', labels=True, dpi=150)
 
 # INTRO EXAMPLE PLOTS
 G = graphs.nX_simple_geoms(G)
@@ -43,7 +43,7 @@
 gravity_cols = cmap(gravity_vals)
 plt.cla()
 plt.clf()
-plot.plot_nX(G_metrics, path='intro_gravity.png', labels=False, colour=gravity_cols)
+plot.plot_nX(G_metrics, path='intro_gravity.png', labels=False, colour=gravity_cols, dpi=150)
 
 # plot hill mixed uses
 mixed_uses_vals = colors.Normalize()(mixed_uses_vals)
@@ -59,26 +59,26 @@
 plt.clf()
 G = mock.mock_graph()
 G = graphs.nX_simple_geoms(G)
-plot.plot_nX(G, path='graph_example.png', labels=True)  # WITH LABELS
+plot.plot_nX(G, path='graph_example.png', labels=True, dpi=150)  # WITH LABELS
 
 #
 #
 # GRAPH MODULE
 plt.cla()
 plt.clf()
-plot.plot_nX(G, path='graph_simple.png', labels=False)  # NO LABELS
+plot.plot_nX(G, path='graph_simple.png', labels=False, dpi=150)  # NO LABELS
 
 G_simple = graphs.nX_simple_geoms(G)
 G_decomposed = graphs.nX_decompose(G_simple, 100)
 
 plt.cla()
 plt.clf()
-plot.plot_nX(G_decomposed, path='graph_decomposed.png', labels=False)
+plot.plot_nX(G_decomposed, path='graph_decomposed.png', labels=False, dpi=150)
 
 plt.cla()
 plt.clf()
 G_dual = graphs.nX_to_dual(G_simple)
-plot.plot_nX_primal_or_dual(G_simple, G_dual, 'graph_dual.png', labels=False)
+plot.plot_nX_primal_or_dual(G_simple, G_dual, 'graph_dual.png', labels=False, dpi=150)
 
 #
 #
@@ -91,7 +91,7 @@
 
 plt.cla()
 plt.clf()
-plot.plot_nX(G, path='graph_before.png', labels=True)
+plot.plot_nX(G, path='graph_before.png', labels=True, dpi=150)
 
 # generate the network layer and compute some metrics
 N = networks.Network_Layer_From_nX(G, distances=[200, 400, 800, 1600])
@@ -102,7 +102,7 @@
 
 plt.cla()
 plt.clf()
-plot.plot_nX(G_post, path='graph_after.png', labels=True)
+plot.plot_nX(G_post, path='graph_after.png', labels=True, dpi=150)
 
 #
 #
@@ -155,7 +155,7 @@
 # plot
 plt.cla()
 plt.clf()
-plot.plot_nX(G_after, path='graph_colour.png', labels=False, colour=cols)
+plot.plot_nX(G_after, path='graph_colour.png', labels=False, colour=cols, dpi=150)
 
 # assignment plot
 data_dict = mock.mock_data_dict(G, random_seed=25)

diff --git a/docs/intro.md b/docs/intro.md
@@ -52,7 +52,7 @@ plot.plot_nX(G, labels=True)
 <img src="./images/plots/graph.png" alt="Example graph" class="centre" style="max-height:500px;">
 
 The [`util.graphs`](/util/graphs.html) module contains a collection of convenience functions for the preparation and conversion of `networkX` graphs, including
-[`nX_wgs_to_utm`](/util/graphs.html#nx-wgs-to-utm) for coordinate conversions; [`nX_remove_filler_nodes`](/util/graphs.html#nx-remove-filler-nodes) for graph cleanup; [`nX_decompose`](/util/graphs.html#nx-decompose) for generating granular graph typologies; and [`nX_to_dual`](/util/graphs.html#nx-to-dual) for casting a primal graph representation to its dual. These functions are designed to work with raw `shapely` [`Linestring`](https://shapely.readthedocs.io/en/latest/manual.html#linestrings) geometries that have been assigned to the edge (link) `geom` attributes. If working with simple graph representations — straight-line edges between nodes — then [`graphs.nX_simple_geoms`](/util/graphs.html#nx-simple-geoms) can generate these geometries for you. The benefit to the use of raw geoms is that the geometry of the network is kept distinct from the topology, and the geometries can therefore be manipulated separately from topological transformations.
+[`nX_wgs_to_utm`](/util/graphs.html#nx-wgs-to-utm) for coordinate conversions; [`nX_remove_dangling_nodes`](/util/graphs.html#nx-remove-dangling-nodes), [`nX_remove_filler_nodes`](/util/graphs.html#nx-remove-filler-nodes), and [`nX_consolidate`](/util/graphs.html#nx-consolidate) for graph cleanup; [`nX_decompose`](/util/graphs.html#nx-decompose) for generating granular graph typologies; and [`nX_to_dual`](/util/graphs.html#nx-to-dual) for casting a primal graph representation to its dual. These functions are designed to work with raw `shapely` [`Linestring`](https://shapely.readthedocs.io/en/latest/manual.html#linestrings) geometries that have been assigned to the edge (link) `geom` attributes. If working with simple graph representations — straight-line edges between nodes — then [`graphs.nX_simple_geoms`](/util/graphs.html#nx-simple-geoms) can generate these geometries for you. The benefit to the use of raw geoms is that the geometry of the network is kept distinct from the topology: the topology is consequently free from distortions which otherwise arise when conflated with geometric representation.
 
 <img src="./images/plots/graph_decomposed.png" alt="Example 100m decomposed graph" class="left"><img src="./images/plots/graph_dual.png" alt="Example dual graph" class="right">
 

diff --git a/docs/util/graphs.md b/docs/util/graphs.md
@@ -54,18 +54,59 @@ A `networkX` graph with `x` and `y` node attributes converted to the local UTM c
 </FuncElement>
 
 
+nX\_remove\_dangling\_nodes <Chip text="v0.8.0"/>
+---------------------------
+
+<FuncSignature>
+<pre>
+nX_remove_dangling_nodes(networkX_graph,
+                         despine=25,
+                         remove_disconnected=True)
+</pre>
+</FuncSignature>
+
+Optionally removes short dead-ends and disconnected graph components, which may be prevalent on poor quality network datasets.
+
+<FuncHeading>Parameters</FuncHeading>
+
+<FuncElement name="networkX_graph" type="nx.Graph">
+
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms.
+
+</FuncElement>
+
+<FuncElement name="despine" type="float">
+
+The maximum cutoff distance for removal of dead-ends. Use `0` where no de-spining should occur.
+
+</FuncElement>
+
+<FuncElement name="remove_disconnected" type="bool">
+
+Whether to remove disconnected components. When set to `True`, only the largest connected component will be returned.
+
+</FuncElement>
+
+<FuncHeading>Returns</FuncHeading>
+<FuncElement name="graph" type="nx.Graph">
+
+A `networkX` graph with disconnected components optionally removed, and dead-ends removed where less than the `despine` distance.
+
+</FuncElement>
+
+
 nX\_remove\_filler\_nodes
 -------------------------
 
 <FuncSignature>nX_remove_filler_nodes(networkX_graph)</FuncSignature>
 
-Removes frivolous nodes where $degree=2$: such nodes represent no route-choices other than continuing-on to the next edge. The edges on either side of the deleted nodes will be removed and replaced with a single new edge, with the `geom` attributes welded together.
+Removes frivolous nodes where $degree=2$: such nodes represent no route-choices other than continuing-on to the next edge. The edges on either side of the deleted nodes will be removed and replaced with a new unified edge. The `geom` attributes welded together.
 
 <FuncHeading>Parameters</FuncHeading>
 
 <FuncElement name="networkX_graph" type="nx.Graph">
 
-A `networkX` graph with `x` and `y` node attributes and `geom` edge attributes containing `LineString` geoms.
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms.
 
 </FuncElement>
 
@@ -81,6 +122,41 @@ Frivolous nodes may be prevalent in poor quality datasets, or in situations wher
 :::
 
 
+nX\_consolidate <Chip text="v0.8.0"/>
+---------------
+
+<FuncSignature>nX_consolidate(networkX_graph, buffer_dist=14, crawl=False)</FuncSignature>
+
+Consolidates nearby nodes within a set buffer distance. This can be useful for situations such as cleaning-up intersections or de-duplicating split roadways.
+
+<FuncHeading>Parameters</FuncHeading>
+
+<FuncElement name="networkX_graph" type="nx.Graph">
+
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms.
+
+</FuncElement>
+
+<FuncElement name="buffer_dist" type="float">
+
+The buffer distance to be used for consolidating nearby nodes.
+
+</FuncElement>
+
+<FuncElement name="crawl" type="bool">
+
+Whether to permit recursive consolidation.
+
+</FuncElement>
+
+<FuncHeading>Returns</FuncHeading>
+<FuncElement name="graph" type="nx.Graph">
+
+A `networkX` graph. Nodes located within the `buffer_dist` distance from other nodes will be consolidated into new parent nodes. The coordinates of the parent nodes will be derived from the centroid of the highest degree constituent nodes. 
+
+</FuncElement>
+
+
 nX\_decompose
 -------------
 
@@ -92,7 +168,7 @@ Decomposes a graph so that no edge is longer than a set maximum. Decomposition p
 
 <FuncElement name="networkX_graph" type="nx.Graph">
 
-A `networkX` graph with `x` and `y` node attributes and `geom` edge attributes containing `LineString` geoms. Optional `live` node attributes.
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms. Optional `live` node attributes.
 
 </FuncElement>
 <FuncElement name="decompose_max" type="nx.Graph">
@@ -142,7 +218,7 @@ Converts a primal graph representation, where intersections are represented as n
 
 <FuncElement name="networkX_graph" type="nx.Graph">
 
-A `networkX` graph with `x` and `y` node attributes and `geom` edge attributes containing `LineString` geoms. Optional `live` node attributes.
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms. Optional `live` node attributes.
 
 </FuncElement>
 
@@ -179,6 +255,7 @@ This function will automatically orient the `geom` attribute LineStrings in the
 
 :::
 
+
 nX\_auto\_edge\_params
 ----------------------
 
@@ -194,7 +271,7 @@ Do not use this function on dual graphs. Dual graphs prepared with [nX_to_dual](
 
 <FuncElement name="networkX_graph" type="nx.Graph">
 
-A `networkX` graph with `geom` edge attributes containing `shapely` `LineString` geoms.
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms.
 
 </FuncElement>
 
@@ -217,7 +294,7 @@ Adds a `weight` node attribute and sets the value to the aggregate half-lengths
 
 <FuncElement name="networkX_graph" type="nx.Graph">
 
-A `networkX` graph with `geom` edge attributes containing `shapely` `LineString` geoms.
+A `networkX` graph in UTM coordinates, containing `x` and `y` node attributes, and a `geom` edge attribute containing `LineString` geoms.
 
 </FuncElement>
 
@@ -248,7 +325,7 @@ It is generally not necessary to use this function directly. This function will
 
 <FuncElement name="networkX_graph" type="nx.Graph">
 
-A `networkX` graph.
+A `networkX` graph in UTM coordinates.
 
 `x` and `y` node attributes are required. The `weight` node attribute is optional, and a default of `1` will be used if not present. The `live` node attribute is optional, but recommended. See [`Network_Layer`](#network-layer) for more information about what these attributes represent.
 

diff --git a/docs/util/mock.md b/docs/util/mock.md
@@ -133,7 +133,7 @@ A 2d `numpy` array containing numerical data elements. The first dimension corre
 
 
 mock\_species\_data
-------------------------
+-------------------
 
 <FuncSignature>mock_species_data(random_seed=None)</FuncSignature>
 
@@ -182,4 +182,44 @@ for counts, probs in mock.mock_species_data():
 
 # etc.
 
-```
+```
+
+
+mock\_osm\_graph
+----------------
+
+<FuncSignature>mock_osm_graph()</FuncSignature>
+
+Generates a `NetworkX` graph for testing or experimentation based on [`Open Street Map`](https://www.openstreetmap.org) data.
+
+::: warning Note
+Note that this graph contains [WGS84](https://epsg.io/4326) `lng`, `lat` geographic coordinates. Use [`graphs.nX_wgs_to_utm`](/util/graphs.html#nx-wgs-to-utm) to cast the graph to the local UTM projected coordinate system.
+:::
+
+<FuncHeading>Returns</FuncHeading>
+<FuncElement name="G" type="nx.Graph">
+
+A `NetworkX` graph with `x` and `y` attributes in [WGS84](https://epsg.io/4326) `lng`, `lat` geographic coordinates.
+
+</FuncElement>
+
+
+mock\_osm\_data
+---------------
+
+<FuncSignature>mock_osm_data()</FuncSignature>
+
+Returns a `JSON` string representing a typical [`Open Street Map`](https://www.openstreetmap.org) response. Used for the purpose of testing.
+
+::: tip Hint
+
+Where the intent is to derive a graph from this data: use [`mock_osm_graph`](#mock-osm-graph) instead.
+
+:::
+
+<FuncHeading>Returns</FuncHeading>
+<FuncElement name="osm_json" type="str">
+
+A `JSON` string representing OSM `nodes` and `ways` data.
+
+</FuncElement>
diff --git a/docs/util/plot.md b/docs/util/plot.md
@@ -17,7 +17,8 @@ plot_nX_primal_or_dual(primal=None,
                        path=None,
                        labels=False,
                        primal_colour=None,
-                       dual_colour=None)
+                       dual_colour=None,
+                       **figure_kwargs)
 </pre>
 </FuncSignature>
 
@@ -60,6 +61,14 @@ Dual node colour or colours. When passing a list of colours, the number of colou
 
 </FuncElement>
 
+</FuncElement>
+
+<FuncElement name="figure_kwargs" type="key=value pairs">
+
+`key=value` pairs which will be passed to the `matplotlib` figure parameters. If provided, these `kwargs` are used to override the default figure size or dpi parameters.
+
+</FuncElement>
+
 ```python
 from cityseer.util import mock, graphs, plot
 
@@ -76,7 +85,16 @@ _Dual graph (blue) overlaid on the source primal graph (red)._
 
 plot\_nX
 --------
-<FuncSignature>plot_nX(networkX_graph, path=None, labels=False, colour=None)</FuncSignature>
+<FuncSignature>
+<pre>
+plot_nX(networkX_graph,
+        path=None,
+        labels=False,
+        colour=None,
+        **figure_kwargs)
+</pre>
+</FuncSignature>
+
 Plot a `networkX` graph.
 
 <FuncHeading>Parameters</FuncHeading>
@@ -104,6 +122,12 @@ Node colour or colours. When passing a list of colours, the number of colours sh
 
 </FuncElement>
 
+<FuncElement name="figure_kwargs" type="key=value pairs">
+
+`key=value` pairs which will be passed to the `matplotlib` figure parameters. If provided, these `kwargs` are used to override the default figure size or dpi parameters.
+
+</FuncElement>
+
 ```python
 from cityseer.util import mock, graphs, plot
 from cityseer.metrics import networks

diff --git a/setup.py b/setup.py
@@ -27,7 +27,7 @@
 
 setup (
     name = 'cityseer',
-    version='0.7.6',
+    version='0.8.0',
     packages=['cityseer', 'cityseer.algos', 'cityseer.metrics', 'cityseer.util'],
     description = 'Computational tools for urban analysis',
     url='https://github.com/cityseer/cityseer-api',