Converting to and from other data formats

xgi.convert.convert_to_graph(H)[source]

Graph projection (1-skeleton) of the hypergraph H. Weights are not considered.

Parameters:

H (Hypergraph object) – The hypergraph of interest

Returns:

G – The graph projection

Return type:

networkx.Graph

xgi.convert.convert_to_hypergraph(data, create_using=None)[source]

Make a hypergraph from a known data structure.

The preferred way to call this is automatically from the class constructor.

Parameters:

  • data (object to be converted) –

    Current known types are:

    • a Hypergraph object

    • a SimplicialComplex object

    • list-of-iterables

    • dict-of-iterables

    • Pandas DataFrame (bipartite edgelist)

    • numpy matrix

    • numpy ndarray

    • scipy sparse matrix

  • create_using (Hypergraph constructor, optional (default=Hypergraph)) – Hypergraph type to create. If hypergraph instance, then cleared before populated.

Returns:

A hypergraph constructed from the data

Return type:

Hypergraph object

xgi.convert.convert_to_simplicial_complex(data, create_using=None)[source]

Make a hypergraph from a known data structure. The preferred way to call this is automatically from the class constructor.

Parameters:

  • data (object to be converted) –

    Current known types are:

    • a SimplicialComplex object

    • a Hypergraph object

    • list-of-iterables

    • dict-of-iterables

    • Pandas DataFrame (bipartite edgelist)

    • numpy matrix

    • numpy ndarray

    • scipy sparse matrix

  • create_using (Hypergraph graph constructor, optional (default=Hypergraph)) – Hypergraph type to create. If hypergraph instance, then cleared before populated.

Returns:

A hypergraph constructed from the data

Return type:

Hypergraph object

xgi.convert.dict_to_hypergraph(data, nodetype=None, edgetype=None, max_order=None)[source]

A function to read a file in a standardized JSON format.

Parameters:

  • data (dict) – A dictionary in the hypergraph JSON format

  • nodetype (type, optional) – Type that the node IDs will be cast to

  • edgetype (type, optional) – Type that the edge IDs will be cast to

  • max_order (int, optional) – Maximum order of edges to add to the hypergraph

Returns:

The loaded hypergraph

Return type:

A Hypergraph object

Raises:

XGIError – If the JSON is not in a format that can be loaded.

See also

read_json

xgi.convert.from_bipartite_graph(G, create_using=None, dual=False)[source]

Create a Hypergraph from a NetworkX bipartite graph.

Any hypergraph may be represented as a bipartite graph where nodes in the first layer are nodes and nodes in the second layer are hyperedges.

The default behavior is to create nodes in the hypergraph from the nodes in the bipartite graph where the attribute bipartite=0 and hyperedges in the hypergraph from the nodes in the bipartite graph with attribute bipartite=1. Setting the keyword dual reverses this behavior.

Parameters:

  • G (nx.Graph) – A networkx bipartite graph. Each node in the graph has a property ‘bipartite’ taking the value of 0 or 1 indicating the type of node.

  • create_using (Hypergraph constructor, optional) – The hypergraph object to add the data to, by default None

  • dual (bool, default : False) – If True, get edges from bipartite=0 and nodes from bipartite=1

Returns:

The equivalent hypergraph

Return type:

Hypergraph

References

The Why, How, and When of Representations for Complex Systems, Leo Torres, Ann S. Blevins, Danielle Bassett, and Tina Eliassi-Rad, https://doi.org/10.1137/20M1355896

Examples

>>> import networkx as nx
>>> import xgi
>>> G = nx.Graph()
>>> G.add_nodes_from([1, 2, 3, 4], bipartite=0)
>>> G.add_nodes_from(['a', 'b', 'c'], bipartite=1)
>>> G.add_edges_from([(1, 'a'), (1, 'b'), (2, 'b'), (2, 'c'), (3, 'c'), (4, 'a')])
>>> H = xgi.from_bipartite_graph(G)
xgi.convert.from_bipartite_pandas_dataframe(df, create_using=None, node_column=0, edge_column=1)[source]

Create a hypergraph from a pandas dataframe given specified node and edge columns.

Parameters:

  • df (Pandas dataframe) – A dataframe where specified columns list the node IDs and the associated edge IDs

  • create_using (Hypergraph constructor, optional) – The hypergraph object to add the data to, by default None

  • node_column (hashable, optional) – The column with the node IDs, by default 0 Can specify names or indices

  • edge_column (hashable, optional) – The column with the edge IDs, by default 1 Can specify names or indices

Returns:

The constructed hypergraph

Return type:

Hypergraph object

Raises:

XGIError – Raises an error if the user specifies invalid column names

xgi.convert.from_hyperedge_dict(d, create_using=None)[source]

Creates a hypergraph from a dictionary of hyperedges

Parameters:

  • d (dict) – A dictionary where the keys are edge IDs and the values are containers of nodes specifying the edges.

  • create_using (Hypergraph constructor, optional) – The hypergraph object to add the data to, by default None

Returns:

The constructed hypergraph object

Return type:

Hypergraph object

See also

to_hyperedge_dict

xgi.convert.from_hyperedge_list(d, create_using=None, max_order=None)[source]

Generate a hypergraph from a list of lists.

Parameters:

  • d (list of iterables) – A hyperedge list

  • create_using (Hypergraph constructor, optional) – The hypergraph to add the edges to, by default None

Returns:

The constructed hypergraph object

Return type:

Hypergraph object

See also

to_hyperedge_list

xgi.convert.from_incidence_matrix(d, create_using=None, nodelabels=None, edgelabels=None)[source]

Create a hypergraph from an incidence matrix

Parameters:

  • d (numpy array or a scipy sparse arrary) – The incidence matrix where rows specify nodes and columns specify edges.

  • create_using (Hypergraph constructor, optional) – The hypergraph object to add the data to, by default None

  • nodelabels (list or 1D numpy array, optional) – The ordered list of node IDs to map the indices of the incidence matrix to, by default None

  • edgelabels (list or 1D numpy array, optional) – The ordered list of edge IDs to map the indices of the incidence matrix to, by default None

Returns:

The constructed hypergraph

Return type:

Hypergraph object

Raises:

XGIError – Raises an error if the specified labels are the wrong dimensions

See also

incidence_matrix, to_incidence_matrix

xgi.convert.from_max_simplices(SC)[source]

Returns a hypergraph constructed from the maximal simplices of the provided simplicial complex.

Parameters:

SC (SimplicialComplex) –

Return type:

Hypergraph

xgi.convert.to_bipartite_graph(H, index=False)[source]

Create a NetworkX bipartite network from a hypergraph.

Parameters:

  • H (xgi.Hypergraph) – The XGI hypergraph object of interest

  • index (bool (default False)) – If False (default), return only the graph. If True, additionally return the index-to-node and index-to-edge mappings.

Returns:

The resulting equivalent bipartite graph, and optionally the index-to-unit mappings.

Return type:

nx.Graph[, dict, dict]

References

The Why, How, and When of Representations for Complex Systems, Leo Torres, Ann S. Blevins, Danielle Bassett, and Tina Eliassi-Rad, https://doi.org/10.1137/20M1355896

Examples

>>> import xgi
>>> hyperedge_list = [[1, 2], [2, 3, 4]]
>>> H = xgi.Hypergraph(hyperedge_list)
>>> G = xgi.to_bipartite_graph(H)
>>> G, itn, ite = xgi.to_bipartite_graph(H, index=True)
xgi.convert.to_bipartite_pandas_dataframe(H)[source]

Create a two column dataframe from a hypergraph.

Parameters:

H (Hypergraph or Simplicial Complex) – A dataframe where specified columns list the node IDs and the associated edge IDs

Returns:

A two column dataframe

Return type:

Pandas Dataframe object

Raises:

XGIError – Raises an error if the user specifies invalid column names

xgi.convert.to_hyperedge_dict(H)[source]

Outputs a hyperedge dictionary

Parameters:

H (Hypergraph object) – The hypergraph of interest

Returns:

A dictionary where the keys are edge IDs and the values are sets of nodes specifying the edges.

Return type:

dict

See also

from_hyperedge_dict

xgi.convert.to_hyperedge_list(H)[source]

Generate a hyperedge list from a hypergraph.

Parameters:

H (Hypergraph object) – The hypergraph of interest

Returns:

The hyperedge list

Return type:

list of sets

See also

from_hyperedge_list

xgi.convert.to_incidence_matrix(H, sparse=True, index=False)[source]

Convert a hypergraph to an incidence matrix.

Parameters:

  • H (Hypergraph object) – The hypergraph of interest

  • sparse (bool, optional) – Whether the constructed incidence matrix should be sparse, by default True

  • index (bool, optional) – Whether to return the corresponding node and edge labels, by default False

Returns:

  • numpy.ndarray or scipy csr_array – The incidence matrix

  • dict – The dictionary mapping indices to node IDs, if index is True

  • dict – The dictionary mapping indices to edge IDs, if index is True

See also

incidence_matrix, from_incidence_matrix

xgi.convert.to_line_graph(H, s=1)[source]

The s-line graph of the hypergraph.

The line graph of the hypergraph H is the graph whose nodes correspond to each hyperedge in H, linked together if they share at least one vertex.

Parameters:

  • H (Hypergraph) – The hypergraph of interest

  • s (int) – The intersection size to consider edges as connected, by default 1.

Returns:

LG – The line graph associated to the Hypergraph

Return type:

networkx.Graph

References

“Hypernetwork science via high-order hypergraph walks”, by Sinan G. Aksoy, Cliff Joslyn, Carlos Ortiz Marrero, Brenda Praggastis & Emilie Purvine. https://doi.org/10.1140/epjds/s13688-020-00231-0