Support DiHypergraph in from_bipartite_graph

[colltoaction]

See #625.

[nwlandry]

@colltoaction --- thanks so much for the contribution! My biggest question is whether the default should be to read/write from a DiGraph. I think that what you've implemented makes sense as well --- maybe we could handle this with a kwarg or something?

[colltoaction]

My understanding is that we always need a MultiGraph, except maybe for half-edges which I don't know.

we mean “pseudographs” in the greatest level of generality, allowing for loops, multiple edges between vertices, and dangling half-edges
https://ncatlab.org/nlab/show/hypergraph#hypergraphs_as_2colored_graphs

I guess using other classes of graphs we get something different than a hypergraph, is this a known structure?

[tlarock]

Thanks for the contribution @colltoaction ! Really useful functionality, I had actually been wondering about how to do this recently.

Wondering if it is possible to achieve this using the original create_using semantics, rather than conditioning on the user correctly setting G.graph.get("network-type") in the bipartite graph? I think we could check if create_using is of type xgi.DiHypergraph (others may reasonably disagree with this approach!), then maybe validate that direction is in the edge-data of the bipartite graph and raise an error if not.

My reasoning is that as written, we ask the user to specify they want a directed hypergraph in 3 different ways: (1) they have to set the "network-type" variable in the bipartite graph to the string "directed"; (2) they need to include "direction" in the edge data; and finally (3) they pass create_using=xgi.DiHypergraph. My suggestion would remove (1) and validate that they have done (2).

On the latter, my potentially wrong understanding is that if a user has not done (2) correctly (e.g., if they accidentaly typed "drection" as the edge-data in the bipartite graph), they will get a DiHypergraph with all heads without warning - is that correct?

Related, but separate: Do we want to allow users to construct simplicial complexes from bipartite graphs? Is that implemented separately? Related because if someone passed create_using=xgi.SimplicialComplex I think it would run fine, but it is not clear whether we intend that or not (to me, the documentation all reads as hypergraphs, not simplicial complexes). @nwlandry let me know if you think I should open a new issue for this one or if it is dealt with somehow.

[colltoaction]

@tlarock for context, some of those decisions are part of the HIF format seen here:

• https://github.com/pszufe/HIF-standard

My intention is to provide a HIF loader for NX that higher-order order libraries can reuse. I.e it should be the same to load from HIF JSON directly to XGI or through an intermediate NX graph then converting it.

• https://github.com/colltoaction/nx_hif

[nwlandry]

@colltoaction @tlarock --- I thought more about the API for this and here is what I would propose:

• have a create_using keyword with default None
• If create_using is None, then Graph and MultiGraph get mapped to Hypergraph and DiGraph and MultiDiGraph get mapped to DiHypergraph
• This default behavior can be overridden with create_using, but maybe there are limitations like, for instance, DiGraph variants can't be mapped to Hypergraph?

[colltoaction]

I updated the PR and would like to point out some comments below