add node_attrs_include param to simplify_graph to flexibly relax strictness

[gboeing]

This PR addresses #625 and #1127, and builds on #1117.

It adds a node_attrs_include param to the simplification.simplify_graph function to flexibly relax graph simplification strictness. If a node has one or more of the attributes in node_attrs_include, it will always be marked as an endpoint. This is useful for capturing the presence of stop signs, traffic signals, and pedestrian crossings in your model of the street network by allowing you to retain these nodes in a simplified graph even if they do not represent a junction of multiple streets. This is often the case with nodes that digitize a traffic signal, for instance, just off the intersection itself.

It also renames the relatively new endpoint_attrs param (introduced in #1117) to edge_attrs_differ for consistent and clear naming, given the new param. The endpoint_attrs param name will be deprecated (#1146) in the next v1 release and removed in the v2.0.0 release.

[gboeing]

@anastassiavybornova @csebastiao @jGaboardi based on your recent comments in #625, I'm pinging you here as you may be interested in this PR. Any comments welcome.

[jGaboardi]

@gboeing Thanks for the ping. I really like the endpoint_attrs -> edge_attrs renaming. Much clearer, especially with the new node_attrs inclusion. Great stuff.

[gboeing]

And just to note, the new node_attrs simplification param allows you control over a node's tag's value as well.

This would be the default graph simplification result:

import osmnx as ox
G = ox.graph.graph_from_place("Piedmont, CA, USA", network_type="drive", simplify=False)
len(G)  # 2918

Gs = ox.simplification.simplify_graph(G)
len(Gs)  # 377

But let's say, for example, that you wanted to only relax simplification for stop signs (i.e., nodes where highway=stop). Instead you'd just use:

for node, data in G.nodes(data=True):
    if data.get("highway") == "stop":
        data["stop"] = True
Gs = ox.simplification.simplify_graph(G, node_attrs=["stop"])
len(Gs)  # 456

This method of marking a node for retention is infinitely configurable. For example, if you want to make sure you retain all nodes denoting stop signs or uncontrolled junctions, you could use:

for node, data in G.nodes(data=True):
    if data.get("highway") == "stop" or data.get("junction") == "uncontrolled":
        data["keep"] = True
Gs = ox.simplification.simplify_graph(G, node_attrs=["keep"])
len(Gs)

[csebastiao]

Thank you for the ping @gboeing ! As @jGaboardi said the node_attrs simplification attribute is a great addition and I also prefer edge_attrs to endpoint_attrs.

If I have some comment to have maybe it's that I'm wondering if the semantic symmetry of node_attrs and edge_attrs might confuse people thinking that they have similar behaviors while they don't. But I don't have anything as clear and concise to propose anyway, something like keep_nodes_with and discriminate_edges_on would be more explicit but also much more verbose.

[gboeing]

Thanks @csebastiao. I had the same conundrum. I too prefer succinct param names, but perhaps it would be best to differentiate them somehow. Maybe just calling the latter edge_attrs_differ would make it clear that they are not symmetrical.

[jGaboardi]

Maybe even edge_attrs_differ & node_attrs_with to be exactly explicit?

[gboeing]

@jGaboardi I like that. Nice and clear. Let's use it.

[gboeing]

I ended up renaming node_attrs to node_attrs_include (instead of node_attrs_with as it seemed even clearer) and edge_attrs to edge_attrs_differ).

[jGaboardi]

I ended up renaming node_attrs to node_attrs_include (instead of node_attrs_with as it seemed even clearer) and edge_attrs to edge_attrs_differ).

Reasonable and clear.

[gboeing]

The first pre-release OSMnx v2 beta has been released. Testers needed! See #1123 for details.