Support directed bearing/orientation distributions and plots

[dhimmel]

What problem does your feature proposal solve?

Creating orientation/bearing distributions and plots for directed graphs.

What is your proposed solution?

_extract_edge_bearings can support directed graphs and in the case of a directed graph skip adding reverse bearings (bearings_r):

osmnx/osmnx/bearing.py

Lines 148 to 191 in 78af8ed

	def _extract_edge_bearings(Gu, min_length=0, weight=None):
	"""
	Extract undirected graph's bidirectional edge bearings.
	For example, if an edge has a bearing of 90 degrees then we will record
	bearings of both 90 degrees and 270 degrees for this edge.
	Parameters
	----------
	Gu : networkx.MultiGraph
	undirected, unprojected graph with `bearing` attributes on each edge
	min_length : float
	ignore edges with `length` attributes less than `min_length`; useful
	to ignore the noise of many very short edges
	weight : string
	if not None, weight edges' bearings by this (non-null) edge attribute.
	for example, if "length" is provided, this will return 1 bearing
	observation per meter per street, which could result in a very large
	`bearings` array.
	Returns
	-------
	bearings : numpy.array
	the graph's bidirectional edge bearings
	"""
	if nx.is_directed(Gu) or projection.is_projected(Gu.graph["crs"]): # pragma: no cover
	msg = "graph must be undirected and unprojected to analyze edge bearings"
	raise ValueError(msg)
	bearings = []
	for u, v, data in Gu.edges(data=True):
	# ignore self-loops and any edges below min_length
	if u != v and data["length"] >= min_length:
	if weight:
	# weight edges' bearings by some edge attribute value
	bearings.extend([data["bearing"]] * int(data[weight]))
	else:
	# don't weight bearings, just take one value per edge
	bearings.append(data["bearing"])
	# drop any nulls, calculate reverse bearings, concatenate and return
	bearings = np.array(bearings)
	bearings = bearings[~np.isnan(bearings)]
	bearings_r = (bearings - 180) % 360
	return np.concatenate([bearings, bearings_r])

What alternatives have you considered?

Implementing bearing calculation, distributions, and plotting outside of osmnx and networkx, but would like to avoid such duplication.

Additional context

Possible use cases are one-way transportation networks or downhill ski trails.

[gboeing]

This would be easy enough to implement but I want to make sure that it's theoretically sound first. I think it may be, though users may need a warning to ensure things proceed according to expectations. That is, should we allow the calculation of bearings on directed graphs?

If a user is interested in the bearings/orientation of flows, then maybe yes. If the user is interested in the bearings/orientation of physical infrastructure, then no. Perhaps a UserWarning as such is sufficient if a user passes a MultiDiGraph instead of a MultiGraph.

[dhimmel]

Thanks @gboeing for your insights here.

should we allow the calculation of bearings on directed graphs? If a user is interested in the bearings/orientation of flows, then maybe yes. If the user is interested in the bearings/orientation of physical infrastructure, then no.

That is a helpful conceptual distinction, although there is certainly a relation between physical infrastructure and flow. Some examples are waterways, separated highways, one ways trails (common in mountain biking, skiing, etc). In all these cases, the physical infrastructure is designed to support directional flow.

Perhaps a UserWarning as such is sufficient if a user passes a MultiDiGraph instead of a MultiGraph.

Another option would be to keep the "graph must be undirected" error unless the user sets an additional argument like directed_bearings=True or omit_reverse=True.

The warning proposal also sounds good paired with documentation like: "Supplying a MultiDiGraph results in directional bearings. For bidirectional bearings, use MultiDiGraph.to_undirected()".

One final note, I initially come to this repository with the hopes of using the bearing calculation and polar histogram plotting without wanting to use a networkx graph. But many of the critical functions required a graph input. Putting the data into the graph was not too hard, but for me was solely for purposes of using the mature and powerful bearing/plotting functionality.

[gboeing]

Would you like to open a PR (targeting the v2 branch) to allow directed graphs, issue a UserWarning and update the docstring?

[dhimmel]

Would you like to open a PR (targeting the v2 branch) to allow directed graphs

Okay will do!

Nice to see the type annotations for v2... will make contributing easier.

[gboeing]

Closed by #1139