Add features to get_edge_data method (migrated from Trac #583)

[networkx-trac]

Original ticket https://networkx.lanl.gov/trac/ticket/583
Reported 2011-06-25 by @dschult, assigned to @dschult.

The get_edge_data method should be enhanced with keyword control of what gets returned.

The motivation for this change is to make it simpler to write algorithms that access edge data, especially when handling multigraphs. See #574 for a detailed discussion and examples.

The proposed signature is:
'''
G.get_edge_data(u,v,key=None,data_key=None,default=1,missing=None,combine=list)
'''
Briefly, when '''data_key is None''', this is like '''G.adj[u][v]'''.
But when '''data_key''' is specified, this is like '''G.adj[u][v].get(data_key, default) '''

If the edge doesn't exist, '''missing''' is returned.

The '''key''' and '''combine''' arguments are used only for multigraphs. If key is specified, use the same behavior on the data dict '''G.adj[u][v][key]'''. If '''key is None''' and '''data_key''' is specified, the list of values obtained is sent to the function combine, which defaults to '''list''', but common examples would be '''min''' or '''sum'''.

This is not backward compatible since the current method uses the '''default''' keyword to supply a value when the edge does not exist instead of when the edge data key does not exist as proposed here.

Suggestions on other desired features? names for arguments? anything else?

[networkx-trac]

Comment in Trac by @hagberg, 2011-06-25

[networkx-trac]

Comment in Trac by @hagberg, 2011-06-25

[networkx-trac]

Comment in Trac by @hagberg, 2011-06-25

[networkx-trac]

Attachment in Trac by @dschult, 2011-06-26: ged.patch

[networkx-trac]

Comment in Trac by @dschult, 2011-06-26

I've attached a patch to implement this suggestion along with tests and a draft of doc_string language.

[networkx-trac]

Comment in Trac by @hagberg, 2011-06-26

Looks good.

Now I'm wondering if the default behavior should be to raise exceptions for missing edge or missing data.

I suppose the keyword would be e.g. missing=None so then you couldn't return a None if you wanted but that seems OK to me.

Raising an exception could help spot errors.

Either way I like default=None better than default=1 since that only makes sense for numerical data.

[networkx-trac]

Comment in Trac by @dschult, 2011-06-27

That sounds good. When default/missing are None, then no data attribute or no missing edge will raise an exception. If you want default behavior you must specify a default/missing value. If someone wants to return None, they can use a try/except clause.

[networkx-trac]

Comment in Trac by @hagberg, 2011-06-27

Here is a patch with the 'raise exception' version. It seems pretty complicated and I've probably not done it correctly or simply or both.

[networkx-trac]

Attachment in Trac by @hagberg, 2011-06-27: get_edge.patch

[networkx-trac]

Comment in Trac by @dschult, 2011-06-28

That patch looks good.

I'm playing with further expansion. (that usually means trouble)

We can make v optional. When v is None, return an iterator over (v, data) for all edges (u,v).
I'll attach a patch that allows
'''
for nbr,edata in G[u].items():
dist = dist_u + edata.get(weight, default)
'''
to be replaced by
'''
for nbr,wt in G.get_edge_data(u, data_key=weight, default=default):
dist = dist_u + wt
'''
This idiom is used in many places and replacing it would allow alternate data structures to return nbr,wt instead of nbr,{'weight',wt}
It doesn't slow down '''G.get_edge_data(u,v)''', and it allows nice looping over edge data.

To go even more extreme, we could allow u to be optional. G.get_edge_data() can return data for all edges.
The question here is whether to return both directions for undirected graphs. The patch does.

I can imagine uses like:
'''
G.size(weight=weight) <=> sum(G.get_edge_data(data_key=weight))/2
'''
The all_edges option might not be as useful as making v optional but neither really affect performance.

Making v optional solves my issues for alternate data structures.

[networkx-trac]

Attachment in Trac by @dschult, 2011-06-28: ged2.patch

[networkx-trac]

Comment in Trac by @hagberg, 2011-06-28

Replying to [comment:8 dschult]:

That patch looks good.

I'm playing with further expansion. (that usually means trouble)

We can make v optional. When v is None, return an iterator over (v, data) for all edges (u,v).

To go even more extreme, we could allow u to be optional. G.get_edge_data() can return data for all edges.

Now this made me reconsider edges() and neighbors() too. It looks like that proposal for get_edge_data() mixes them all together.

I don't like having one big method like a Swiss-army knife. We are inching towards '''G.get_edge_data(**kwds)''' that will get any piece of data you want from the graph.

I think I understand that you are trying to abstract the fact that we are using dictionaries as edge data. I don't see any clean way to do that (everytime a method returns "data" you'd need to optionally allow a data_key, missing, etc). At that point wouldn't it be better to have a custom edge class?