classes package

class classes.Hypergraph(setsystem=None, default_cell_weight=1, edge_col=0, node_col=1, cell_weight_col='weight', misc_cell_properties_col=None, aggregate_by='first', properties=None, misc_properties_col=None, weight_prop_col='weight', default_weight: float | int = 1, edge_properties=None, misc_edge_properties_col=None, edge_weight_prop_col='weight', default_edge_weight=1, node_properties=None, misc_node_properties_col=None, node_weight_prop_col='weight', default_node_weight=1, name=None, **kwargs)[source]

Bases: object

Parameters:

setsystem (pandas.DataFrame, dict of iterables, dict of dicts, list of iterables, numpy.ndarray, optional, default=None) – See SetSystem below for additional setsystem requirements.
edge_col (str | int, optional, default=0) – column index (or name) in pandas.DataFrame, used for (hyper)edge ids. Only used when setsystem is a pandas.DataFrame
node_col (str | int, optional, default=1) – column index (or name) in pandas.dataframe, used for node ids. Only used when setsystem is a pandas.DataFrame
cell_weight_col (str | int, optional, default="weight") – column index (or name) in pandas.DataFrame used for referencing cell weights. For a dict of dicts, it will be used as a key in the nested dictionary of properties. These are the same as edge dependent node weights and will populate the incidence matrix when weights=True.
default_cell_weight (int | float, optional, default=1) – All incidence pairs in the Hypergraph are assigned a default weight if weight is not specified in the setsystem.
misc_cell_properties_col (str | int, optional, default=None) – Used for Pandas Dataframe with one column containing dictionaries of properties. Useful if objects have diverse property sets. Ignored for other setsystem types.
properties (pd.DataFrame | dict, optional, default=None) – Concatenation/union of edge_properties and node_properties. By default, the object id is used and should be the first column of the dataframe, or key in the dict. If there are nodes and edges with the same ids but distinct properties then separate them and use the edge_properties and node_properties keywords.
weight_prop_col (str, optional, default=None) – Name of property in properties to use for weight
default_weight (int | float, optional, default=1) – Used when weight property is missing or undefined
edge_properties (pd.DataFrame | dict, optional, default=None) – Properties associated with edge ids. If a dataframe, the first column must be the names of the edges. First column of dataframe or keys of dict link to edge ids in setsystem.
edge_weight_prop_col (str, optional, default=None) – Name of property in edge_properties to use for weight.
default_edge_weight (int | float, optional, default=1) – Used when edge weight property is missing or undefined.
node_properties (pd.DataFrame | dict, optional, default=None) – Properties associated with node ids. If a dataframe, the first column must be the names of the nodes. First column of dataframe or keys of dict link to nodes ids in setsystem.
node_weight_prop_col (str, optional, default=None) – Name of property in node_properties to use for weight.
default_node_weight (int | float, optional, default=1) – Used when node weight property is missing or undefined
misc_properties_col (str | int, optional, default=None) – Used for properties, edge_properties, and node_properties Pandas Dataframes with one column containing dictionaries of properties. Useful if objects have diverse property sets. Ignored for other setsystem types.
name (str, optional, default=None) – Name assigned to hypergraph

Hypergraphs in HNX 2.3

An hnx.Hypergraph H = (V,E) references a pair of disjoint sets: V = nodes (vertices) and E = (hyper)edges.

HNX allows for multi-edges by distinguishing edges by their unique identifiers instead of their contents. For example, if V = {1,2,3} and E = {e1,e2,e3}, where e1 = {1,2}, e2 = {1,2}, and e3 = {1,2,3}, the edges e1 and e2 contain the same set of nodes and yet are distinct and are distinguishable within H = (V,E).

New as of version 2.3, HNX provides methods to easily store and access additional metadata such as cell, edge, and node weights. Metadata associated with all edges, nodes, and (edge,node) incidence pairs stored in the hypergraph are viewable using:

>>> H.edges.to_dataframe
>>> H.nodes.to_dataframe
>>> H.incidences.to_dataframe

The fundamental object needed to create a hypergraph is a setsystem. The setsystem defines the many-to-many relationships between edges and nodes in the hypergraph. Properties for the incidence pairs are defined within the setsystem. Properties for the edges and nodes are defined with separate Pandas DataFrames or dictionaries.

A hypergraph is defined by its relationships. While the nodes and edges are distinct objects with their own properties, it is only when they are in a relationship (i.e. incidence pair) that nodes and egdges are viewable within the hypergraph structure. Consequently, hypergraph metrics and combinatorics do not use “isolated” nodes or “empty” edges. For example, while node_properties could contain any number of node identifiers, only nodes belonging to an edge in the hypergraph are counted when computing the size and shape of the hypergraph.

SetSystems

There are five types of setsystems currently accepted by the library.

iterable of iterables : Barebones hypergraph, which uses Pandas default indexing to generate hyperedge ids. Elements must be hashable.:
```
>>> list_of_lists = [['book','candle','cat'],['book','coffee cup'],['coffee cup','radio']]
>>> H = Hypergraph(list_of_lists)
```

dictionary of iterables : The most basic way to express many-to-many relationships providing edge ids. The elements of the iterables must be hashable):

>>> scenes_dictionary = {
>>>     0: ('FN', 'TH'),
>>>     1: ('TH', 'JV'),
>>>     2: ('BM', 'FN', 'JA'),
>>>     3: ('JV', 'JU', 'CH', 'BM'),
>>>     4: ('JU', 'CH', 'BR', 'CN', 'CC', 'JV', 'BM'),
>>>     5: ('TH', 'GP'),
>>>     6: ('GP', 'MP'),
>>>     7: ('MA', 'GP'),
>>>     8: ('FN', 'TH')}
>>> H = hnx.Hypergraph(scenes_dictionary)

dictionary of dictionaries : allows cell properties to be assigned to a specific (edge, node) incidence. This is particularly useful when there are variable length dictionaries assigned to each pair:

>>> nested_dictionary =  {
>>>     0: {'FN':{'time':'early', 'weight': 7}, 'TH':{'time':'late'}},
>>>     1: {'TH':{'subject':'war'}, 'JV':{'observed_by':'someone'}},
>>>     2: {'BM':{}, 'FN':{}, 'JA':{'role':'policeman'}},
>>>     3: {'JV':{'was_carrying':'stick'}, 'JU':{}, 'CH':{}, 'BM':{'state':'intoxicated', 'color':'pinkish'}},
>>>     4: {'JU':{'weight':15}, 'CH':{}, 'BR':{'state':'worried'}, 'CN':{}, 'CC':{}, 'JV':{}, 'BM':{}},
>>>     5: {'TH':{}, 'GP':{}},
>>>     6: {'GP':{}, 'MP':{}},
>>>     7: {'MA':{}, 'GP':{'accompanied_by':'dog', 'weight':15, 'was_singing': 'Frère Jacques'}}}
>>> H = hnx.Hypergraph(nested_dictionary)

pandas.DataFrame For large datasets and for datasets with cell properties it is most efficient to construct a hypergraph directly from a pandas.DataFrame. Incidence pairs are in the first two columns. Cell properties shared by all incidence pairs can be placed in their own column of the dataframe. Variable length dictionaries of cell properties particular to only some of the incidence pairs may be placed in a single column of the dataframe. Representing the data above as a dataframe df:

col1

col2

w

col3

e1

1

0.5

{‘name’:’related_to’}

e1

2

0.1

{“name”:”related_to”,
“startdate”:”05.13.2020”}

e2

1

0.52

{“name”:”owned_by”}

The first row of the dataframe is used to reference each column.
```
>>> import pandas as pd
>>> d = {'col1': ['e1', 'e1', 'e2'],
>>>      'col2': [1, 2, 1],
>>>      'w': [0.5, 0.1, 0.52],
>>>      'col3':[{'name': 'related_to'}, {'name': 'related_to', 'startdate':'05.13.2020'}, {'name': 'owned_by'}]}
>>> df = pd.DataFrame(d)
>>> H = hnx.Hypergraph(df, edge_col="col1", node_col="col2",
>>>                    cell_weight_col="w", misc_cell_properties_col="col3")
```
numpy.ndarray For homogeneous datasets given in a n x 2 ndarray a pandas dataframe is generated. In this case, the constructor will only accept properties for the edges and nodes using the edge and node uids listed in the array, although incidence properties can be added after construction:
```
>>> import numpy as np
>>> np_array = np.array([['A','a'],['A','b'],['A','c'],['B','a'],['B','d'],['C','c'],['C','d']])
>>> H = hnx.Hypergraph(np_array)
>>> H.incidences[('A','a')].color = 'red'
>>> H.dataframe
```

Edge and Node Properties

Properties specific to a single edge or node are passed through the keywords: edge_properties, node_properties, or properties. Properties may be passed as dataframes or dictionaries. The first column or index of the dataframe or the keys of the dictionary correspond to the edge and/or node identifiers. If identifiers are shared among edges and nodes, or are distinct for edges and nodes, properties may be combined into a single object and passed to the properties keyword. For example:

uid

weight

properties

e1

5.0

{‘type’:’event’}

e2

0.52

{“name”:”owned_by”}

…

…

{…}

1

1.2

{‘color’:’red’}

2

.003

{‘name’:’Fido’,’color’:’brown’}

3

1.0

{}

A properties dictionary should have the format:

dp = {uid1 : {prop1:val1, prop2:val2, ...},
      uid2 : {...},
      ...}

Weights

The default key for cell and object weights is “weight”. The default value is 1. Weights may be assigned from a column in the dataframe by specifying the column and/or a new default in the constructor using cell_weight_col and default_cell_weight for incidence pairs, and using edge_weight_prop_col, default_edge_weight for edges, node_weight_prop_col, default_node_weight for nodes, and weight_prop_col, default_weight for a shared property dataframe.

add_edge(edge_uid, inplace=True, **attr)[source]

Add a single edge with attributes to edge properties. Does not add an incidence to the hypergraph.

Parameters:

edge_uid (int | str) – edge_uid
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.
**attr (dict, optional) – Properties to add to edges as key=value pairs.

Return type:

Hypergraph

add_edges_from(edge_uids, inplace=True)[source]

Add a collection of edges with attributes to edge properties. Does not add an incidence to the hypergraph.

Parameters:

edge_uids (list[int | str] | list[tuple[int | str, dict]], list[int | str | tuple[int | str, dict]]) – edge_uids must be a list of uids and/or tuples of the form (uid,data) where data is dictionary
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Return type:

Hypergraph

add_incidence(edge_uid, node_uid, inplace=True, **attr)[source]

Add a single incidence with attributes to Hypergraph.

Parameters:

edge_uid (int | str) – edge_uid
node_uid (int | str) – node_uid
inplace (bool, optional, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.
**attr (dict, optional) – Properties to add to incidences as key=value pairs.

Returns:

Hypergraph with incidences added.

Return type:

Hypergraph

add_incidences_from(incidences, inplace=True)[source]

Adds a collection of incidences to Hypergraph

Parameters:

incidences (list[str | int, str | int], list[tuple[str | int, str | int, dict[str, Any]]) – Incidence pairs must be a list of uids of the form (edge_uid,node_uid) and/or tuples of the form (edge_uid, node_uid,data) where data is a dictionary.
inplace (bool, optional, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Returns:

Hypergraph with incidences added.

Return type:

Hypergraph

add_node(node_uid, inplace=True, **attr)[source]

Add a single node with attributes to node properties. Does not add an incidence to the hypergraph.

Parameters:

node_uid (int | str) – node_uid
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.
**attr (dict, optional) – Properties to add to edges as key=value pairs.

Return type:

Hypergraph

add_nodes_from(node_uids, inplace=True)[source]

Add a collection of nodes with attributes to nodes properties. Does not add an incidence to the hypergraph.

Parameters:

node_uids (list[int | str] | list[tuple[int | str, dict]], list[int | str | tuple[int | str, dict]]) – node_uids must be a list of uids and/or tuples of the form (uid,data) where data is dictionary
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Return type:

Hypergraph

add_nodes_to_edges(edge_dict, inplace=True)[source]

Adds a collection of incidences to Hypergraph

Parameters:

edge_dict (dict[str, list[str | int] | dict[str, dict]]) – The edge dictionary must be a dictionary of edges as the keys and a list of nodes or a dictionary of nodes to properties as the values.
inplace (bool, default=True) – If True, changes the existing. Otherwise, creates a new Hypergraph with the requested changes.

Returns:

Hypergraph with the updated edges and their newly added nodes

Return type:

Hypergraph

adjacency_matrix(s=1, index=False)[source]

Returns the s-adjacency matrix for the hypergraph.

Parameters:

s (int, optional, default=1)
index (boolean, optional, default=False) – If True, returns both the adjacency matrix and an array containing the row and column index of node_uids

Returns:

adjacency matrix (scipy.sparse.csr_matrix)
node indexes (np.ndarray) – an np.ndarray containing the row and column index of node_uids.

auxiliary_matrix(s=1, node=True, index=False)[source]

The unweighted s-auxiliary matrix for hypergraph

Parameters:

s (int, optional, default=1)
node (bool, optional, default=True) – whether to return based on node or edge adjacencies
index (bool, optional, default=False) – If True, returns both the auxiliary matrix and an array containing the row and column index of node or edge_uids

Returns:

auxiliary matrix (scipy.sparse.csr_matrix) – Node/Edge adjacency matrix with empty rows and columns removed
index (np.ndarray) – row and column index of node or edge uids

bipartite(keep_data=False, directed=False)[source]

Creates a bipartite NetworkX graph from hypergraph. The nodes and (hyper)edges of hypergraph become the nodes of bipartite graph. For every (hyper)edge e in the hypergraph and node v in e there is an edge (e,v) in the graph.

Parameters:

keep_data (bool, optional, default = False) – If True the node and edge data from the hypergraph will be added to the NetworkX graph
directed (bool, optional, default = False) – If True the graph edges will be directed so that the hypergraph edges are the sources and the hypergraph nodes are the targets

Return type:

networkx.Graph or DiGraph

clone(name=None)[source]

Create a deep copy of the hypergraph

Parameters:: name (str, optional, default = None)
Return type:: Hypergraph

collapse_edges(name=None, use_uids=None, use_counts=False, return_counts=True, return_equivalence_classes=False, aggregate_edges_by=None, aggregate_cells_by=None)[source]

Returns a new hypergraph by collapsing edges.

Parameters:

name (str, optional, default = None)
use_uids (list, optional, default = None) – Specify the edge identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_counts (boolean, optional, default = False) – Rename the equivalence class representatives as <uid>:<size of class>
return_counts (bool, optional, default = True) – Add the size of the equivalence class to the properties associated to the representative in the collapsed hypergraph using keyword: eclass_size
return_equivalence_classes (boolean, optional, default = False) – Returns a dictionary of edge equivalence classes keyed by a representative from each class
aggregate_edges_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries
aggregate_cells_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries

Return type:

Hypergraph

Notes

Collapses the edges of Hypergraph. Two edges are duplicates if their respective elements are the same. Using this as an equivalence relation, the uids of the edges are partitioned into equivalence classes. A single member of the equivalence class is chosen to represent the class.

Example

>>> data = {'E1': ('a', 'b'), 'E2': ('a', 'b')}
>>> h = Hypergraph(data)
>>> h.incidence_dict
{'E1': ['a', 'b'], 'E2': ['a', 'b']}
>>> h.collapse_edges().incidence_dict
{'E1': ['a', 'b']}
>>> h.collapse_edges(use_counts=True).incidence_dict
{'E1:2': ['a', 'b']}
>>> h.collapse_edges().properties.to_dict(orient='records')
[{'weight': 2.0, 'misc_properties': {}}, {'weight': 2.0, 'misc_properties': {}}]

collapse_nodes(name=None, use_uids=None, use_counts=False, return_counts=True, return_equivalence_classes=False, aggregate_nodes_by=None, aggregate_cells_by=None)[source]

Returns a new hypergraph by collapsing nodes.

Parameters:

name (str, optional, default = None)
use_uids (list, optional, default = None) – Specify the node identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_counts (boolean, optional, default = False) – Rename the equivalence class representatives as <uid>:<size of class>
return_counts (bool, optional, default = True) – Add the size of the equivalence class to the properties associated to the representative in the collapsed hypergraph using keyword: eclass_size
return_equivalence_classes (boolean, optional, default = False) – Returns a dictionary of edge equivalence classes keyed by a representative from each class
aggregate_nodes_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries
aggregate_cells_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries

Return type:

Hypergraph

Notes

Collapses the nodes of Hypergraph. Two nodes are duplicates if their respective memberships are the same. Using this as an equivalence relation, the uids of the nodes are partitioned into equivalence classes. A single member of the equivalence class is chosen to represent the class.

Example

>>> data = {'E1': ('a', 'b'), 'E2': ('a', 'b')}
>>> h = Hypergraph(data)
>>> h.incidence_dict
{'E1': ['a', 'b'], 'E2': ['a', 'b']}
>>> h.collapse_nodes().incidence_dict
{'E1': ['a'], 'E2': ['a']}
>>> h.collapse_nodes(use_counts=True).incidence_dict
{'E1: ['a:2'], 'E2': ['a:2']}
>>> h.collapse_nodes().properties.to_dict(orient='records')
[{'weight': 2.0, 'misc_properties': {}}, {'weight': 2.0, 'misc_properties': {}}]

collapse_nodes_and_edges(name=None, use_edge_uids=None, use_node_uids=None, use_counts=False, return_counts=True, return_equivalence_classes=False, aggregate_nodes_by=None, aggregate_edges_by=None, aggregate_cells_by=None)[source]

Returns a new hypergraph by collapsing nodes and edges.

Parameters:

name (str, optional, default = None)
return_equivalence_classes (boolean, optional, default = False) – Returns a dictionary of edge equivalence classes keyed by a representative from each class
use_edge_uids (list, optional, default = None) – Specify the edge and node identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_node_uids (list, optional, default = None) – Specify the edge and node identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_counts (boolean, optional, default = False) – Rename the equivalence class representatives as <uid>:<size of class>
return_counts (bool, optional, default = True) – Add the size of the equivalence class to the properties associated to the representative in the collapsed hypergraph using keyword: eclass_size
aggregate_nodes_by (optional) – default = {‘weight’ = ‘sum’}, all Method to combine duplicate rows of data for the same uids
aggregate_edges_by (optional) – default = {‘weight’ = ‘sum’}, all Method to combine duplicate rows of data for the same uids
aggregate_cells_by (optional) – default = {‘weight’ = ‘sum’}, all Method to combine duplicate rows of data for the same uids

Returns:

new hypergraph (Hypergraph)
node equivalence classes (dict)
edge equivalence classes (dict)

Notes

Collapses the Nodes and Edges of Hypergraph. Two nodes(edges) are duplicates if their respective memberships(elements) are the same. Using this as an equivalence relation, the uids of the nodes(edges) are partitioned into equivalence classes. A single member of the equivalence class is chosen to represent the class.

Example

>>> data = {'E1': ('a', 'b'), 'E2': ('a', 'b')}
>>> h = Hypergraph(data)
>>> h.incidence_dict
{'E1': ['a', 'b'], 'E2': ['a', 'b']}
>>> h.collapse_nodes_and_edges().incidence_dict
{'E1': ['a']}
>>> h.collapse_nodes_and_edges(use_counts=True).incidence_dict
{'E1:2': ['a:2']}

component_subgraphs(return_singletons=False, name=None)[source]: Same as s_components_subgraphs() with s=1. Returns iterator.

See also

s_component_subgraphs

components(edges=False)[source]: Same as s_connected_components() with s=1, but nodes are returned by default. Return iterator.

See also

s_connected_components

connected_component_subgraphs(return_singletons=True, name=None)[source]: Same as s_component_subgraphs() with s=1. Returns iterator

See also

s_component_subgraphs

connected_components(edges=False)[source]: Same as s_connected_components() with s=1, but nodes are returned by default. Return iterator.

See also

s_connected_components

property dataframe

Returns dataframe of incidence properties as dataframe with edges and nodes in columns.

Return type:: pandas.DataFrame

degree(node_uid, s=1, max_size=None)[source]

The number of edges of size at least s and at most max_size that contain the node.

Parameters:

node_uid (hashable) – Identifier for the node.
s (int, optional, default=1) – The smallest size (must be positive) of an edge to consider in degree.
max_size (int, optional, default=None) – The largest size (must be positive) of edge to consider in degree.

Returns:

The number of edges of size at least s and at most max_size that contain the node.

Return type:

int

diameter(s=1)[source]

Returns the length of the longest shortest s-walk between nodes in hypergraph

Parameters:: s (int, optional, default=1)
Returns:: diameter
Return type:: int
Raises:: HyperNetXError – If hypergraph is not s-edge-connected

Notes

Two nodes are s-adjacent if they share s edges. Two nodes v_start and v_end are s-walk connected if there is a sequence of nodes v_start, v_1, v_2, … v_n-1, v_end such that consecutive nodes are s-adjacent. If the graph is not connected, an error will be raised.

difference(other, name=None)[source]

Hypergraph obtained by restricting to incidences in self but not in other.

Parameters:

other (Hypergraph)
name (str, optional, default = None)

Return type:

Hypergraph

dim(edge)[source]

Same as size(edge) - 1()

Parameters:: edge (hashable) – The uid of an edge in the hypergraph
Return type:: int

distance(source, target, s=1)[source]

Returns the shortest s-walk distance between two nodes in the hypergraph.

Parameters:

source (str | int) – a node in the hypergraph
target (str | int) – a node in the hypergraph
s (positive int, optional, default=1) – the number of edges

Returns:

s-walk distance

Return type:

int

See also

edge_distance

Notes

The s-distance is the shortest s-walk length between the nodes. An s-walk between nodes is a sequence of nodes that pairwise share at least s edges. The length of the shortest s-walk is 1 less than the number of nodes in the path sequence.

Uses the networkx shortest_path_length method on the graph generated by the s-adjacency matrix.

dual(name=None, share_properties=True)[source]

Constructs a new hypergraph with roles of edges and nodes of hypergraph reversed.

Parameters:

name (hashable, optional, default=None)
share_properties (bool, optional, default=True) – Whether to tie the edge and node properties of objects in the dual to objects in the hypergraph. If True, a change to edge and node properties in one will be reflected in the other.

Return type:

Hypergraph

edge_adjacency_matrix(s=1, index=False)[source]

Returns the s-adjacency matrix for the dual hypergraph.

Parameters:

s (int, optional, default=1)
index (boolean, optional, default=False) – If True, returns both the adjacency matrix and an array containing the row and column index of edge_uids

Returns:

edge adjacency matrix (scipy.sparse.csr_matrix)
edge indexes (np.ndarray) – an np.ndarray containing the row and column index of edge_uids.

Notes

This is also the adjacency matrix for the line graph. Two edges are s-adjacent if they share at least s nodes.

edge_diameter(s=1)[source]

Returns the length of the longest shortest s-walk between edges in the hypergraph

Parameters:: s (int, optional, default=1)
Returns:: edge_diameter
Return type:: int
Raises:: HyperNetXError – If hypergraph is not s-edge-connected

Notes

Two edges are s-adjacent if they share s nodes. Two nodes e_start and e_end are s-walk connected if there is a sequence of edges e_start, e_1, e_2, … e_n-1, e_end such that consecutive edges are s-adjacent. If the graph is not connected, an error will be raised.

edge_diameters(s=1)[source]

Returns the edge diameters of the s_edge_connected component subgraphs in the hypergraph.

Parameters:: s (int, optional, default=1)
Returns:: maximum diameter, list of diameters, list of component – maximum diameter, list of diameters (List of edge_diameters for s-edge component subgraphs in hypergraph), list of component (List of the edge uids in the s-edge component subgraphs)
Return type:: tuple[int, list, list]

edge_distance(source, target, s=1)[source]

Returns the shortest s-walk distance between two edges in the hypergraph.

Parameters:

source (str | int) – an edge in the hypergraph
target (str | int) – an edge in the hypergraph
s (positive int, optional, default=1) – the number of intersections between pairwise consecutive edges

Returns:

s-walk distance – The shortest s-walk edge distance. A shortest s-walk is computed as a sequence of edges; the s-walk distance is the number of edges in the sequence minus 1. If no such path exists returns np.inf.

Return type:

int | float

See also

distance

Notes

The s-distance is the shortest s-walk length between the edges. An s-walk between edges is a sequence of edges such that consecutive pairwise edges intersect in at least s nodes. The length of the shortest s-walk is 1 less than the number of edges in the path sequence.

Uses the networkx shortest_path_length method on the graph generated by the s-edge_adjacency matrix.

edge_neighbors(edge, s=1)[source]

The edges in hypergraph which share s nodes(s) with edge.

Parameters:

edge (hashable) – uid for an edge in hypergraph
s (int, optional, default=1) – Minimum number of nodes shared by neighbors edge node.

Returns:

a list of edge neighbors

Return type:

list

edge_size_dist()[source]

Returns the size for each edge.

Returns:: a list of sizes of each edge.
Return type:: list

property edges

Object associated with edges.

Return type:: HypergraphView

equivalence_classes(edges=True)[source]

Returns the equivalence classes created by collapsing edges or nodes.

Parameters:: edges (bool, optional, default=True) – If True collapses edges, otherwise collapses nodes.
Returns:: A list of sets of edges or nodes
Return type:: list

classmethod from_bipartite(B, node_id=1, name=None, **kwargs)[source]

Static method creates a Hypergraph from a NetworkX bipartite graph. Still to come: capturing edge and node properties from the graph for use in the hypergraph.

Parameters:

B (nx.Graph()) – A networkx bipartite graph. Each node in the graph has a property ‘bipartite’ taking the value of 0 or 1 indicating a 2-coloring of the graph.
node_id (int) – bipartite value assigned to graph nodes that will be hypergraph edges
name (hashable, optional)

Return type:

Hypergraph

Notes

A partition for the nodes in a bipartite graph generates a hypergraph.

>>> import networkx as nx
>>> B = nx.Graph()
>>> B.add_nodes_from([1, 2, 3, 4], bipartite=0)
>>> B.add_nodes_from(['a', 'b', 'c'], bipartite=1)
>>> B.add_edges_from([(1, 'a'), (1, 'b'), (2, 'b'), (2, 'c'), (3, 'c'), (4, 'a')])
>>> H = Hypergraph.from_bipartite(B, nodes=1)
>>> list(H.nodes), list(H.edges)
(['a', 'b', 'c'], [1, 2, 3, 4])

classmethod from_incidence_dataframe(df, name=None, fillna=0, key=None, return_only_dataframe=False, **kwargs)[source]

Create a hypergraph from a Pandas Dataframe object, which has values equal to the incidence matrix of a hypergraph. Its index will identify the nodes and its columns will identify its edges.

Parameters:

df (Pandas.Dataframe) – a real valued dataframe with a single index
name ((optional) string, default = None)
fillna (float, default = 0) – a real value to place in empty cell, all-zero columns will not generate an edge.
key ((optional) function, default = None) – boolean function to be applied to dataframe. will be applied to entire dataframe.
return_only_dataframe ((optional) bool, default = False) – to use the incidence_dataframe with cell_properties or properties, set this to true and use it as the setsystem in the Hypergraph constructor.

See also

from_numpy_array

Return type:: Hypergraph | pd.DataFrame

classmethod from_incidence_matrix(M, name=None, **kwargs)[source]: Accepts numpy.matrix or scipy.sparse matrix

classmethod from_numpy_array(M, node_names=None, edge_names=None, name=None, key=None, **kwargs)[source]

Create a hypergraph from a real valued matrix represented as a 2 dimensional numpy array. The matrix is converted to a matrix of 0’s and 1’s so that any truthy cells are converted to 1’s and all others to 0’s.

Parameters:

M (real valued array-like object, 2 dimensions) – representing a real valued matrix with rows corresponding to nodes and columns to edges
node_names (object, array-like, default=None) – List of node names must be the same length as M.shape[0]. If None then the node names correspond to row indices with ‘v’ prepended.
edge_names (object, array-like, default=None) – List of edge names must have the same length as M.shape[1]. If None then the edge names correspond to column indices with ‘e’ prepended.
name (hashable)
key ((optional) function) – boolean function to be evaluated on each cell of the array, must be applicable to numpy.array

Return type:

Hypergraph

Note

The constructor does not generate empty edges. All zero columns in M are removed and the names corresponding to these edges are discarded.

get_cell_properties(edge_uid, node_uid, prop_name=None)[source]

Get cell properties on a specified edge and node

Parameters:

edge_uid (str | int) – edge_uid
node_uid (str | int) – node_uid
prop_name (str, optional, default=None) – name of a cell property; if None, all cell properties will be returned

Returns:

cell property value if prop_name is provided, otherwise dict of all cell properties and values

Return type:

Any

get_linegraph(s=1, edges=True)[source]

Creates an s-linegraph for the Hypergraph. If edges=True, then the edges will be the vertices of the line graph. Two vertices are connected by an s-line-graph edge if the corresponding hypergraph edges intersect in at least s hypergraph nodes. If edges=False, the hypergraph nodes will be the vertices of the line graph. Two vertices are connected if the nodes they correspond to share at least s incident (hyper)edges.

Parameters:

s (int) – The width of the connections.
edges (bool, optional, default = True) – Determine if edges or nodes will be the vertices in the linegraph.

Returns:

A NetworkX graph.

Return type:

nx.Graph

get_properties(uid, level=0, prop_name=None)[source]

Returns an object’s specific property or all properties

Parameters:

uid (hashable) – edge or node id
level (int | None , optional, default=0) – Enter 0 for edges and 1 for nodes.
prop_name (str | None, optional, default=None) – if None then all properties associated with the object will be returned.

Returns:

single property or dictionary of properties

Return type:

Any

incidence_dataframe(weights=False)[source]

property incidence_dict

Dictionary keyed by edge uids with values as the uids of nodes of each edge

Return type:: dict

incidence_matrix(index=False, weights=False)[source]

A sparse matrix indicating the existence of an incidence pair in the hypergraph. Each row corresponds to a node v and each column corresponds to an edge e. The entry corresponding to (row v, col e) is nonzero if v is an element of e. If weights = True then the value equals the weight given in the hypergraph incidence properties for the incidence pair (e,v). Otherwise, the value is 1.

Parameters:

index (bool, optional, default = False) – If index=True, returns a tuple containing the incidence matrix, an np.ndarray containing the row and column index of node_uids, and an np.ndarray containing the row and column index of edge_uids. Otherwise, returns the incidence matrix.
weights (bool, optional, default = False) – If True, use the incidence weights corresponding to the row and column of the entry.

Returns:

incidence matrix (scipy.sparse.csr_matrix)
node indexes (np.ndarray) – an np.ndarray containing the row and column index of node_uids
edge indexes (np.ndarray) – an np.ndarray containing the row and column index of edge_uids

property incidences

Object associated with incidence pairs

Return type:: HypergraphView

intersection(other, name=None)[source]

Returns a hypergraph created by restricting to incidence pairs contained in both self and other. Properties inherited from self.

Parameters:

other (Hypergraph)
name (str, optional, default=None)

Return type:

Hypergraph

is_connected(s=1, edges=False)[source]

Determines if hypergraph is s-connected.

Parameters:

s (int, optional, default=1)
edges (boolean, optional, default=False) – If True, will determine if s-edge-connected. For s=1 s-edge-connected is the same as s-connected.

Returns:

is_connected

Return type:

boolean

Notes

A hypergraph is s node connected if for any two nodes v0,vn there exists a sequence of nodes v0,v1,v2,…,v(n-1),vn such that every consecutive pair of nodes v(i),v(i+1) share at least s edges.

A hypergraph is s edge connected if for any two edges e0,en there exists a sequence of edges e0,e1,e2,…,e(n-1),en such that every consecutive pair of edges e(i),e(i+1) share at least s nodes.

neighbors(node, s=1)[source]

The nodes in hypergraph which share s edge(s) with node.

Parameters:

node (hashable) – uid for a node in hypergraph
s (int, optional, default=1) – Minimum number of edges shared by neighbors with node.

Returns:

neighbors – s-neighbors share at least s edges in the hypergraph

Return type:

list

node_diameters(s=1)[source]

Returns the node diameters of the connected components in the hypergraph.

Parameters:: s (int, optional, default=1)
Returns:: maximum diameter, list of diameters, list of component – maximum diameter, list of diameters (List of node_diameters for s-node component subgraphs in hypergraph), list of component (List of the node uids in the s-node component subgraphs)
Return type:: tuple[int, list, list]

property nodes

Object associated with nodes.

Return type:: HypergraphView

order()[source]

The number of nodes in hypergraph.

Returns:: order
Return type:: int

property properties

Returns incidence properties

Return type:: pandas.DataFrame

remove_edges(edge_uids, name=None, inplace=True)[source]

Removes the edges from the Hypergraph. If inplace=True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Parameters:

edge_uids (str | int | list[str | int]) – edge_uids
name (str, optional, default=None) – The name of the new Hypergraph. Used only when inplace=False; ignored if inplace=True.
inplace (bool, optional, default=True) – Whether to replace the current hypergraph with a new one.

Return type:

Hypergraph

remove_incidences(incidence_uids, name=None, inplace=True)[source]

Removes the incidences from the Hypergraph. If inplace=True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Parameters:

incidence_uids (tuple[str | int] | list[tuple[str | int]]) – incidence_uids
name (str, optional, default=None) – The name of the new Hypergraph. Used only when inplace=False; ignored if inplace=True.
inplace (bool, optional, default=True) – Whether to replace the current hypergraph with a new one.

Return type:

Hypergraph

remove_nodes(node_uids, name=None, inplace=True)[source]

Removes the nodes from the Hypergraph. If inplace=True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Parameters:

node_uids (str | int | list[str | int]) – node_uids
name (str, optional, default=None) – The name of the new Hypergraph. Used only when inplace=False; ignored if inplace=True.
inplace (bool, optional, default=True) – Whether to replace the current hypergraph with a new one.

Return type:

Hypergraph

remove_singletons(name=None)[source]

Constructs clone of hypergraph with singleton edges removed.

Parameters:: name (str, optional, default=None)
Return type:: Hypergraph

rename(edges=None, nodes=None, name=None, inplace=True)[source]

Rename the edges and/or nodes of the hypergraph.

Parameters:

edges (dict, optional, default = None) – dictionary of replacement edge_uids
nodes (dict, optional, default = None) – dictionary of replacement node_uids
name (str, optional, default=None)
inplace (bool, optional, default=True)

Return type:

Hypergraph

restrict_to_edges(edges, name=None)[source]

New hypergraph gotten by restricting to edges

Parameters:

edges (Iterable) – edge identifiers to restrict to
name (str | int, optional, default=None) – edge identifier

Return type:

Hypergraph

restrict_to_nodes(nodes, name=None)[source]

New hypergraph gotten by restricting to nodes

Parameters:

nodes (Iterable) – node identifiers to restrict to
name (str | int, optional, default=None) – node identifier

Return type:

Hypergraph

s_component_subgraphs(s=1, edges=True, return_singletons=False, name=None)[source]

Returns a generator for the induced subgraphs of s_connected components. Removes singletons unless return_singletons is set to True. Computed using s-linegraph generated either by the hypergraph (edges=True) or its dual (edges = False)

Parameters:

s (int, optional, default=1)
edges (boolean, optional, default=False) – Determines if edge or node components are desired. Returns subgraphs equal to the hypergraph restricted to each set of nodes(edges) in the s-connected components or s-edge-connected components
return_singletons (bool, optional, default=False) – If True, keep singletons in subgraph. Otherwise, remove singletons.
name (str, optional, default=None)

Yields:

s_component_subgraphs (iterator) – Iterator returns subgraphs generated by the edges (or nodes) in the s-edge(node) components of hypergraph.

s_components(s=1, edges=True, return_singletons=True)[source]: Same as s_connected_components()

See also

s_connected_components

s_connected_components(s=1, edges=True, return_singletons=False)[source]

Returns a generator for the s-edge-connected component or the s-node-connected component of the hypergraph.

Parameters:

s (int, optional, default=1)
edges (boolean, optional, default=True) – If True, return edge components; otherwise, return node components
return_singletons (bool, optional, default=False) – If True, keep singletons. Otherwise, remove singletons

Notes

If edges=True, this method returns the s-edge-connected components as lists of lists of edge uids. An s-edge-component has the property that for any two edges e1 and e2 there is a sequence of edges starting with e1 and ending with e2 such that pairwise adjacent edges in the sequence intersect in at least s nodes. If s=1 these are the path components of the hypergraph.

If edges=False this method returns s-node-connected components. A list of sets of uids of the nodes which are s-walk connected. Two nodes v1 and v2 are s-walk-connected if there is a sequence of nodes starting with v1 and ending with v2 such that pairwise adjacent nodes in the sequence share s edges. If s=1 these are the path components of the hypergraph.

Example

>>> S = {'A':{1,2,3},'B':{2,3,4},'C':{5,6},'D':{6}}
>>> H = Hypergraph(S)

>>> list(H.s_connected_components(edges=True))
[{'C', 'D'}, {'A', 'B'}]
>>> list(H.s_connected_components(edges=False))
[{1, 2, 3, 4}, {5, 6}]

Yields:: s_connected_components (iterator) – Iterator returns sets of uids of the edges (or nodes) in the s-edge(node) components of hypergraph.

set_state(**kwargs)[source]

Allow state_dict updates from outside of class. Use with caution.

Parameters:: **kwargs (dict, optional) – key-value pairs to save in state dictionary

property shape

The number of nodes, number of edges

Returns:: number of nodes, number of edges
Return type:: tuple

singletons()[source]

Returns a list of singleton edges. A singleton edge is an edge of size 1 with a node of degree 1.

Returns:: singles – A list of edge uids.
Return type:: list

size(edge, nodeset=None)[source]

The number of nodes in nodeset that belong to edge. If nodeset is None then returns the size of edge

Parameters:: edge (hashable) – The uid of an edge in the hypergraph
Returns:: size
Return type:: int

sum(other, name=None)[source]

Hypergraph obtained by joining incidences from self and other. Removes duplicates and uses properties of self.

Parameters:: other (Hypergraph)
Return type:: Hypergraph

toplexes(return_hyp=False)[source]

Computes a maximal collection of toplexes for the hypergraph. A toplex is a hyperedge, which is not contained in any other hyperedge. If return_hyp=True, then returns the simple hypergraph created by restricting to the toplexes.

Parameters:: return_hyp (bool, optional, default=False)
Return type:: Hypergraph | list

union(other, name=None)[source]

The hypergraph gotten by joining incidence pairs contained in self and other. Duplicates removed. Properties inherited from self. Same as sum()

Parameters:

other (Hypergraph)
name (str, optional, default=None)

Return type:

Hypergraph

class classes.HypergraphView(incidence_store, level, property_store=None)[source]

Bases: object

Wrapper for Property and Incidence Stores holding structural and metadata for hypergraph. Provides methods matching EntitySet methods in previous versions. Only nodes and edges in the Incidence Store will be seeable in this view.

property dataframe

All properties for objects in the HypergraphView. Same as to_dataframe.

Return type:: pd.DataFrame

property default_weight

Default weight for an edge, node, or incidence

Return type:: int | float

property elements

See elements

Return type:: dict

property incidence_dict

incidence dictionary

Return type:: dict | None

property incidence_store

IncidenceStore

Return type:: IncidenceStore

is_empty()[source]

Returns true if HypergraphView has no edges, nodes, or incidences depending on the level; otherwise, false

Return type:: bool

property items

If level 0 or 1, the list of edges or nodes, respectively. If level 2, the IncidenceStore

Return type:: IncidenceStore | array

property level

0 = Edges, 1 = Nodes, 2 = Incidences

Return type:: int
Type:: The type of store

property memberships

See memberships

Return type:: dict

property properties

All properties for objects in the HypergraphView. Same as to_dataframe.

Return type:: pd.DataFrame

property property_store

PropertyStore

Return type:: PropertyStore

set_defaults(defaults_dict)[source]

Creates or updates default values in PropertyStore associated with this HypergraphView. Does not overwrite existing user-defined properties

Parameters:: defaults_dict (dict) – Dictionary of prop_names to their default values
Return type:: None

property to_dataframe

Dataframe of properties (user defined and default) for all items in the HypergraphView. Creates a properties dataframe of non-user-defined items with default values. Combines user-defined and non-user-defined properties into one dataframe.

Return type:: pd.DataFrame

property user_defined_properties

User-defined properties. Does not include items in the HypergraphView that the user has not explicitly defined properties for.

Return type:: pd.DataFrame

class classes.IncidenceStore(data)[source]

Bases: object

Incidence store object that stores and accesses (multi) incidences with standard methods.

Parameters:: data (Two column pandas dataframe of edges and nodes, respectively.)

collapse_identical_elements(level, use_keys=None)[source]

property data

property dimensions

The number of distinct edges and nodes in that order

Returns:: Tuple of size two of (number of unique edges, number of unique nodes).
Return type:: tuple of ints

property edges

Returns an array of edge names from the incidence pairs

Returns:: Returns an array of edge names
Return type:: array

property elements

equivalence_classes(level=0)[source]

property memberships

neighbors(level, key)[source]

Returns elements or memberships depending on level.

Parameters:

level (int) – Level indicator for finding either elements or memberships. For level 0 (elements), returns nodes in the edge. For level 1 (memberships), returns edges containing the node.
key (int or str) – Name of node or edge depending on level.

Returns:

Elements or memberships (depending on level) of a given edge or node, respectively.

Return type:

list

property nodes

Returns an array of node names from the incidence pairs

Returns:: Returns an array of node names
Return type:: array

restrict_to(level, items, inplace=False)[source]

returns IncidenceStore of subset of incidence store restricted to pairs with items in the given level Will return with same data or deepcopy depending on inplace

Parameters:

level (int) – Level indicator for finding either elements or memberships. For level 0 (elements), returns nodes in the edge. For level 1 (memberships), returns edges containing the node.
items (list) – List of uids to be removed from level
inplace (bool, optional) – whether to replace self, by default False

Returns:

subset of incidence store given a restriction.

Return type:

list

class classes.PropertyStore(data=None, default_weight=1)[source]

Bases: object

Class for storing properties of a collection of edges, nodes, or incidences.

Properties will be stored in a pandas dataframe.

copy(deep=False)[source]

Create a copy of the PropertyStore. If deep=True, create a copy of the underlying data table. Otherwise, use the same underlying data table from the original PropertyStore

Parameters:: deep (bool, optional, default=False)
Return type:: PropertyStore

property default_properties: dict

Returns copy of default dictionary of properties

Returns:: Dictionary of properties automatically given to objects either in the property store if no user defined values have been assigned to them or objects that have not yet been added to the Property Store.
Return type:: dict

get_properties(uid) → dict[source]

Get all properties of an item

Parameters:: uid (Hashable) – uid is the index used to fetch all its properties
Returns:: Output dictionary containing all properties of the uid. {named property: property value, ..., properties: {property name: property value}}
Return type:: dict

See also

get_property, set_property

get_property(uid, prop_name) → Any[source]

Get a property of an item

Parameters:

uid (Hashable) – uid is the index used to fetch its property
prop_name (str | int) – name of the property to get

Returns:

out (Any) – value of the property
None – if property not found

See also

get_properties, set_property

property properties: DataFrame

Properties assigned to all items in the underlying data table

Returns:

a dataframe with the following columns:: uid, weight, properties, <optional props> or level, id, weight, properties, <optional props>

Return type:

pandas.DataFrame

set_defaults(defaults) → None[source]

Set default values for properties

Parameters:: defaults (dict)
Return type:: None

set_properties(uid, props) → None[source]

Parameters:

uid (Hashable) – uid is the index used to set its property
props (a dictionary containing user-defined properties)

Return type:

None

set_property(uid, prop_name, prop_val) → None[source]

Set a property of an item in the ‘properties’ collection

Parameters:

uid (Hashable) – uid is the index used to set its property
prop_name (str | int) – name of the property to set
prop_val (any) – value of the property to set

Return type:

None

Submodules

classes.factory module

classes.factory.create_df(dfp, uid_cols=None, level=0, use_index=False, weight_prop=None, default_weight=1.0, misc_properties_col=None, aggregation_methods=None)[source]

classes.factory.dataframe_factory_method(DF, level, use_indices=False, uid_cols=None, misc_properties_col='misc_properties', weight_col='weight', default_weight=1.0, aggregate_by={})[source]

This function creates a pandas dataframe in the correct format given a pandas dataframe of either cell, node, or edge properties.

Parameters:

DF (dataframe) – dataframe of properties for either incidences, edges, or nodes
level (int) – Level to specify the type of data the dataframe is for: 0 for edges, 1 for nodes, and 2 for incidences (cells).
uid_cols (list of str or int) – column index (or name) in pandas.dataframe used for (hyper)edge, node, or incidence (edge, node) IDs.

misc_properties_col(optional) int | str, default = None: Column of property dataframes with dtype=dict. Intended for variable length property dictionaries for the objects.
weight_col(optional) str, default = None,: Name of property in edge_properties to use for weight.
default_weight(optional) int | float, default = 1: Used when edge weight property is missing or undefined.
aggregate_by(optional) dict, default = {}: By default duplicate incidences will be dropped unless specified with aggregation_methods. See pandas.DataFrame.agg() methods for additional syntax and usage information. An example aggregation method is {‘weight’: ‘sum’} to sum the weights of the aggregated duplicate rows.

Return type:: Pandas Dataframe of the property store in the correct format for HNX.

classes.factory.dict_factory_method(Dct, level, use_indices=False, uid_cols=None, misc_properties_col='misc_properties', weight_col='weight', default_weight=1.0, aggregate_by={})[source]

This function creates a pandas dataframe in the correct format given a dictionary of either cell, node, or edge properties.

Parameters:

Dct (dictionary) – dictionary of properties for either incidences, edges, or nodes
level (int) – Level to specify the type of data the dataframe is for: 0 for edges, 1 for nodes, and 2 for incidences (cells).
uid_cols (list of str or int) – column index (or name) in pandas.dataframe used for (hyper)edge, node, or incidence (edge, node) IDs.
misc_properties_col ((optional) int | str, default = None) – Column of property dataframes with dtype=dict. Intended for variable length property dictionaries for the objects.
weight_col ((optional) str, default = None,) – Name of property in edge_properties to use for weight.
default_weight ((optional) int | float, default = 1) – Used when edge weight property is missing or undefined.
aggregate_by ((optional) dict, default = {}) – By default duplicate incidences will be dropped unless specified with aggregation_methods. See pandas.DataFrame.agg() methods for additional syntax and usage information. An example aggregation method is {‘weight’: ‘sum’} to sum the weights of the aggregated duplicate rows.
"""

Return type:

Pandas Dataframe of the property store in the correct format for HNX.

classes.factory.dict_to_incidence_store_df(D)[source]

classes.factory.list_factory_method(L, level, use_indices=False, uid_cols=None, misc_properties_col='misc_properties', weight_col='weight', default_weight=1.0, aggregate_by={})[source]

This function creates a pandas dataframe in the correct format given a list of lists to be used as the cell property store dataframe.

Parameters:

L (list of lists) – list of lists representing the nodes in each hyperedge.
level (int) – Level to specify the type of data the dataframe is for: 0 for edges, 1 for nodes, and 2 for incidences (cells).
uid_cols (list of str or int) – column index (or name) in pandas.dataframe used for (hyper)edge, node, or incidence (edge, node) IDs.
misc_properties_col ((optional) int | str, default = None) – Column of property dataframes with dtype=dict. Intended for variable length property dictionaries for the objects.
weight_col ((optional) str, default = None,) – Name of property in edge_properties to use for weight.
default_weight ((optional) int | float, default = 1) – Used when edge weight property is missing or undefined.
aggregate_by ((optional) dict, default = {}) – By default duplicate incidences will be dropped unless specified with aggregation_methods. See pandas.DataFrame.agg() methods for additional syntax and usage information. An example aggregation method is {‘weight’: ‘sum’} to sum the weights of the aggregated duplicate rows.
"""

Return type:

Pandas Dataframe of the property store in the correct format for HNX.

classes.factory.mkdict(x)[source]

classes.factory.ndarray_factory_method(arr, level, *args, **kwargs)[source]

classes.hyp_view module

class classes.hyp_view.HypergraphView(incidence_store, level, property_store=None)[source]

Bases: object

Wrapper for Property and Incidence Stores holding structural and metadata for hypergraph. Provides methods matching EntitySet methods in previous versions. Only nodes and edges in the Incidence Store will be seeable in this view.

property dataframe

All properties for objects in the HypergraphView. Same as to_dataframe.

Return type:: pd.DataFrame

property default_weight

Default weight for an edge, node, or incidence

Return type:: int | float

property elements

See elements

Return type:: dict

property incidence_dict

incidence dictionary

Return type:: dict | None

property incidence_store

IncidenceStore

Return type:: IncidenceStore

is_empty()[source]

Returns true if HypergraphView has no edges, nodes, or incidences depending on the level; otherwise, false

Return type:: bool

property items

If level 0 or 1, the list of edges or nodes, respectively. If level 2, the IncidenceStore

Return type:: IncidenceStore | array

property level

0 = Edges, 1 = Nodes, 2 = Incidences

Return type:: int
Type:: The type of store

property memberships

See memberships

Return type:: dict

property properties

All properties for objects in the HypergraphView. Same as to_dataframe.

Return type:: pd.DataFrame

property property_store

PropertyStore

Return type:: PropertyStore

set_defaults(defaults_dict)[source]

Creates or updates default values in PropertyStore associated with this HypergraphView. Does not overwrite existing user-defined properties

Parameters:: defaults_dict (dict) – Dictionary of prop_names to their default values
Return type:: None

property to_dataframe

Dataframe of properties (user defined and default) for all items in the HypergraphView. Creates a properties dataframe of non-user-defined items with default values. Combines user-defined and non-user-defined properties into one dataframe.

Return type:: pd.DataFrame

property user_defined_properties

User-defined properties. Does not include items in the HypergraphView that the user has not explicitly defined properties for.

Return type:: pd.DataFrame

classes.hypergraph module

class classes.hypergraph.Hypergraph(setsystem=None, default_cell_weight=1, edge_col=0, node_col=1, cell_weight_col='weight', misc_cell_properties_col=None, aggregate_by='first', properties=None, misc_properties_col=None, weight_prop_col='weight', default_weight: float | int = 1, edge_properties=None, misc_edge_properties_col=None, edge_weight_prop_col='weight', default_edge_weight=1, node_properties=None, misc_node_properties_col=None, node_weight_prop_col='weight', default_node_weight=1, name=None, **kwargs)[source]

Bases: object

Parameters:

setsystem (pandas.DataFrame, dict of iterables, dict of dicts, list of iterables, numpy.ndarray, optional, default=None) – See SetSystem below for additional setsystem requirements.
edge_col (str | int, optional, default=0) – column index (or name) in pandas.DataFrame, used for (hyper)edge ids. Only used when setsystem is a pandas.DataFrame
node_col (str | int, optional, default=1) – column index (or name) in pandas.dataframe, used for node ids. Only used when setsystem is a pandas.DataFrame
cell_weight_col (str | int, optional, default="weight") – column index (or name) in pandas.DataFrame used for referencing cell weights. For a dict of dicts, it will be used as a key in the nested dictionary of properties. These are the same as edge dependent node weights and will populate the incidence matrix when weights=True.
default_cell_weight (int | float, optional, default=1) – All incidence pairs in the Hypergraph are assigned a default weight if weight is not specified in the setsystem.
misc_cell_properties_col (str | int, optional, default=None) – Used for Pandas Dataframe with one column containing dictionaries of properties. Useful if objects have diverse property sets. Ignored for other setsystem types.
properties (pd.DataFrame | dict, optional, default=None) – Concatenation/union of edge_properties and node_properties. By default, the object id is used and should be the first column of the dataframe, or key in the dict. If there are nodes and edges with the same ids but distinct properties then separate them and use the edge_properties and node_properties keywords.
weight_prop_col (str, optional, default=None) – Name of property in properties to use for weight
default_weight (int | float, optional, default=1) – Used when weight property is missing or undefined
edge_properties (pd.DataFrame | dict, optional, default=None) – Properties associated with edge ids. If a dataframe, the first column must be the names of the edges. First column of dataframe or keys of dict link to edge ids in setsystem.
edge_weight_prop_col (str, optional, default=None) – Name of property in edge_properties to use for weight.
default_edge_weight (int | float, optional, default=1) – Used when edge weight property is missing or undefined.
node_properties (pd.DataFrame | dict, optional, default=None) – Properties associated with node ids. If a dataframe, the first column must be the names of the nodes. First column of dataframe or keys of dict link to nodes ids in setsystem.
node_weight_prop_col (str, optional, default=None) – Name of property in node_properties to use for weight.
default_node_weight (int | float, optional, default=1) – Used when node weight property is missing or undefined
misc_properties_col (str | int, optional, default=None) – Used for properties, edge_properties, and node_properties Pandas Dataframes with one column containing dictionaries of properties. Useful if objects have diverse property sets. Ignored for other setsystem types.
name (str, optional, default=None) – Name assigned to hypergraph

Hypergraphs in HNX 2.3

An hnx.Hypergraph H = (V,E) references a pair of disjoint sets: V = nodes (vertices) and E = (hyper)edges.

HNX allows for multi-edges by distinguishing edges by their unique identifiers instead of their contents. For example, if V = {1,2,3} and E = {e1,e2,e3}, where e1 = {1,2}, e2 = {1,2}, and e3 = {1,2,3}, the edges e1 and e2 contain the same set of nodes and yet are distinct and are distinguishable within H = (V,E).

New as of version 2.3, HNX provides methods to easily store and access additional metadata such as cell, edge, and node weights. Metadata associated with all edges, nodes, and (edge,node) incidence pairs stored in the hypergraph are viewable using:

>>> H.edges.to_dataframe
>>> H.nodes.to_dataframe
>>> H.incidences.to_dataframe

The fundamental object needed to create a hypergraph is a setsystem. The setsystem defines the many-to-many relationships between edges and nodes in the hypergraph. Properties for the incidence pairs are defined within the setsystem. Properties for the edges and nodes are defined with separate Pandas DataFrames or dictionaries.

A hypergraph is defined by its relationships. While the nodes and edges are distinct objects with their own properties, it is only when they are in a relationship (i.e. incidence pair) that nodes and egdges are viewable within the hypergraph structure. Consequently, hypergraph metrics and combinatorics do not use “isolated” nodes or “empty” edges. For example, while node_properties could contain any number of node identifiers, only nodes belonging to an edge in the hypergraph are counted when computing the size and shape of the hypergraph.

SetSystems

There are five types of setsystems currently accepted by the library.

iterable of iterables : Barebones hypergraph, which uses Pandas default indexing to generate hyperedge ids. Elements must be hashable.:
```
>>> list_of_lists = [['book','candle','cat'],['book','coffee cup'],['coffee cup','radio']]
>>> H = Hypergraph(list_of_lists)
```

dictionary of iterables : The most basic way to express many-to-many relationships providing edge ids. The elements of the iterables must be hashable):

>>> scenes_dictionary = {
>>>     0: ('FN', 'TH'),
>>>     1: ('TH', 'JV'),
>>>     2: ('BM', 'FN', 'JA'),
>>>     3: ('JV', 'JU', 'CH', 'BM'),
>>>     4: ('JU', 'CH', 'BR', 'CN', 'CC', 'JV', 'BM'),
>>>     5: ('TH', 'GP'),
>>>     6: ('GP', 'MP'),
>>>     7: ('MA', 'GP'),
>>>     8: ('FN', 'TH')}
>>> H = hnx.Hypergraph(scenes_dictionary)

dictionary of dictionaries : allows cell properties to be assigned to a specific (edge, node) incidence. This is particularly useful when there are variable length dictionaries assigned to each pair:

>>> nested_dictionary =  {
>>>     0: {'FN':{'time':'early', 'weight': 7}, 'TH':{'time':'late'}},
>>>     1: {'TH':{'subject':'war'}, 'JV':{'observed_by':'someone'}},
>>>     2: {'BM':{}, 'FN':{}, 'JA':{'role':'policeman'}},
>>>     3: {'JV':{'was_carrying':'stick'}, 'JU':{}, 'CH':{}, 'BM':{'state':'intoxicated', 'color':'pinkish'}},
>>>     4: {'JU':{'weight':15}, 'CH':{}, 'BR':{'state':'worried'}, 'CN':{}, 'CC':{}, 'JV':{}, 'BM':{}},
>>>     5: {'TH':{}, 'GP':{}},
>>>     6: {'GP':{}, 'MP':{}},
>>>     7: {'MA':{}, 'GP':{'accompanied_by':'dog', 'weight':15, 'was_singing': 'Frère Jacques'}}}
>>> H = hnx.Hypergraph(nested_dictionary)

pandas.DataFrame For large datasets and for datasets with cell properties it is most efficient to construct a hypergraph directly from a pandas.DataFrame. Incidence pairs are in the first two columns. Cell properties shared by all incidence pairs can be placed in their own column of the dataframe. Variable length dictionaries of cell properties particular to only some of the incidence pairs may be placed in a single column of the dataframe. Representing the data above as a dataframe df:

col1

col2

w

col3

e1

1

0.5

{‘name’:’related_to’}

e1

2

0.1

{“name”:”related_to”,
“startdate”:”05.13.2020”}

e2

1

0.52

{“name”:”owned_by”}

The first row of the dataframe is used to reference each column.
```
>>> import pandas as pd
>>> d = {'col1': ['e1', 'e1', 'e2'],
>>>      'col2': [1, 2, 1],
>>>      'w': [0.5, 0.1, 0.52],
>>>      'col3':[{'name': 'related_to'}, {'name': 'related_to', 'startdate':'05.13.2020'}, {'name': 'owned_by'}]}
>>> df = pd.DataFrame(d)
>>> H = hnx.Hypergraph(df, edge_col="col1", node_col="col2",
>>>                    cell_weight_col="w", misc_cell_properties_col="col3")
```
numpy.ndarray For homogeneous datasets given in a n x 2 ndarray a pandas dataframe is generated. In this case, the constructor will only accept properties for the edges and nodes using the edge and node uids listed in the array, although incidence properties can be added after construction:
```
>>> import numpy as np
>>> np_array = np.array([['A','a'],['A','b'],['A','c'],['B','a'],['B','d'],['C','c'],['C','d']])
>>> H = hnx.Hypergraph(np_array)
>>> H.incidences[('A','a')].color = 'red'
>>> H.dataframe
```

Edge and Node Properties

Properties specific to a single edge or node are passed through the keywords: edge_properties, node_properties, or properties. Properties may be passed as dataframes or dictionaries. The first column or index of the dataframe or the keys of the dictionary correspond to the edge and/or node identifiers. If identifiers are shared among edges and nodes, or are distinct for edges and nodes, properties may be combined into a single object and passed to the properties keyword. For example:

uid

weight

properties

e1

5.0

{‘type’:’event’}

e2

0.52

{“name”:”owned_by”}

…

…

{…}

1

1.2

{‘color’:’red’}

2

.003

{‘name’:’Fido’,’color’:’brown’}

3

1.0

{}

A properties dictionary should have the format:

dp = {uid1 : {prop1:val1, prop2:val2, ...},
      uid2 : {...},
      ...}

Weights

The default key for cell and object weights is “weight”. The default value is 1. Weights may be assigned from a column in the dataframe by specifying the column and/or a new default in the constructor using cell_weight_col and default_cell_weight for incidence pairs, and using edge_weight_prop_col, default_edge_weight for edges, node_weight_prop_col, default_node_weight for nodes, and weight_prop_col, default_weight for a shared property dataframe.

add_edge(edge_uid, inplace=True, **attr)[source]

Add a single edge with attributes to edge properties. Does not add an incidence to the hypergraph.

Parameters:

edge_uid (int | str) – edge_uid
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.
**attr (dict, optional) – Properties to add to edges as key=value pairs.

Return type:

Hypergraph

add_edges_from(edge_uids, inplace=True)[source]

Add a collection of edges with attributes to edge properties. Does not add an incidence to the hypergraph.

Parameters:

edge_uids (list[int | str] | list[tuple[int | str, dict]], list[int | str | tuple[int | str, dict]]) – edge_uids must be a list of uids and/or tuples of the form (uid,data) where data is dictionary
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Return type:

Hypergraph

add_incidence(edge_uid, node_uid, inplace=True, **attr)[source]

Add a single incidence with attributes to Hypergraph.

Parameters:

edge_uid (int | str) – edge_uid
node_uid (int | str) – node_uid
inplace (bool, optional, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.
**attr (dict, optional) – Properties to add to incidences as key=value pairs.

Returns:

Hypergraph with incidences added.

Return type:

Hypergraph

add_incidences_from(incidences, inplace=True)[source]

Adds a collection of incidences to Hypergraph

Parameters:

incidences (list[str | int, str | int], list[tuple[str | int, str | int, dict[str, Any]]) – Incidence pairs must be a list of uids of the form (edge_uid,node_uid) and/or tuples of the form (edge_uid, node_uid,data) where data is a dictionary.
inplace (bool, optional, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Returns:

Hypergraph with incidences added.

Return type:

Hypergraph

add_node(node_uid, inplace=True, **attr)[source]

Add a single node with attributes to node properties. Does not add an incidence to the hypergraph.

Parameters:

node_uid (int | str) – node_uid
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.
**attr (dict, optional) – Properties to add to edges as key=value pairs.

Return type:

Hypergraph

add_nodes_from(node_uids, inplace=True)[source]

Add a collection of nodes with attributes to nodes properties. Does not add an incidence to the hypergraph.

Parameters:

node_uids (list[int | str] | list[tuple[int | str, dict]], list[int | str | tuple[int | str, dict]]) – node_uids must be a list of uids and/or tuples of the form (uid,data) where data is dictionary
inplace (bool, default=True) – If True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Return type:

Hypergraph

add_nodes_to_edges(edge_dict, inplace=True)[source]

Adds a collection of incidences to Hypergraph

Parameters:

edge_dict (dict[str, list[str | int] | dict[str, dict]]) – The edge dictionary must be a dictionary of edges as the keys and a list of nodes or a dictionary of nodes to properties as the values.
inplace (bool, default=True) – If True, changes the existing. Otherwise, creates a new Hypergraph with the requested changes.

Returns:

Hypergraph with the updated edges and their newly added nodes

Return type:

Hypergraph

adjacency_matrix(s=1, index=False)[source]

Returns the s-adjacency matrix for the hypergraph.

Parameters:

s (int, optional, default=1)
index (boolean, optional, default=False) – If True, returns both the adjacency matrix and an array containing the row and column index of node_uids

Returns:

adjacency matrix (scipy.sparse.csr_matrix)
node indexes (np.ndarray) – an np.ndarray containing the row and column index of node_uids.

auxiliary_matrix(s=1, node=True, index=False)[source]

The unweighted s-auxiliary matrix for hypergraph

Parameters:

s (int, optional, default=1)
node (bool, optional, default=True) – whether to return based on node or edge adjacencies
index (bool, optional, default=False) – If True, returns both the auxiliary matrix and an array containing the row and column index of node or edge_uids

Returns:

auxiliary matrix (scipy.sparse.csr_matrix) – Node/Edge adjacency matrix with empty rows and columns removed
index (np.ndarray) – row and column index of node or edge uids

bipartite(keep_data=False, directed=False)[source]

Creates a bipartite NetworkX graph from hypergraph. The nodes and (hyper)edges of hypergraph become the nodes of bipartite graph. For every (hyper)edge e in the hypergraph and node v in e there is an edge (e,v) in the graph.

Parameters:

keep_data (bool, optional, default = False) – If True the node and edge data from the hypergraph will be added to the NetworkX graph
directed (bool, optional, default = False) – If True the graph edges will be directed so that the hypergraph edges are the sources and the hypergraph nodes are the targets

Return type:

networkx.Graph or DiGraph

clone(name=None)[source]

Create a deep copy of the hypergraph

Parameters:: name (str, optional, default = None)
Return type:: Hypergraph

collapse_edges(name=None, use_uids=None, use_counts=False, return_counts=True, return_equivalence_classes=False, aggregate_edges_by=None, aggregate_cells_by=None)[source]

Returns a new hypergraph by collapsing edges.

Parameters:

name (str, optional, default = None)
use_uids (list, optional, default = None) – Specify the edge identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_counts (boolean, optional, default = False) – Rename the equivalence class representatives as <uid>:<size of class>
return_counts (bool, optional, default = True) – Add the size of the equivalence class to the properties associated to the representative in the collapsed hypergraph using keyword: eclass_size
return_equivalence_classes (boolean, optional, default = False) – Returns a dictionary of edge equivalence classes keyed by a representative from each class
aggregate_edges_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries
aggregate_cells_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries

Return type:

Hypergraph

Notes

Collapses the edges of Hypergraph. Two edges are duplicates if their respective elements are the same. Using this as an equivalence relation, the uids of the edges are partitioned into equivalence classes. A single member of the equivalence class is chosen to represent the class.

Example

>>> data = {'E1': ('a', 'b'), 'E2': ('a', 'b')}
>>> h = Hypergraph(data)
>>> h.incidence_dict
{'E1': ['a', 'b'], 'E2': ['a', 'b']}
>>> h.collapse_edges().incidence_dict
{'E1': ['a', 'b']}
>>> h.collapse_edges(use_counts=True).incidence_dict
{'E1:2': ['a', 'b']}
>>> h.collapse_edges().properties.to_dict(orient='records')
[{'weight': 2.0, 'misc_properties': {}}, {'weight': 2.0, 'misc_properties': {}}]

collapse_nodes(name=None, use_uids=None, use_counts=False, return_counts=True, return_equivalence_classes=False, aggregate_nodes_by=None, aggregate_cells_by=None)[source]

Returns a new hypergraph by collapsing nodes.

Parameters:

name (str, optional, default = None)
use_uids (list, optional, default = None) – Specify the node identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_counts (boolean, optional, default = False) – Rename the equivalence class representatives as <uid>:<size of class>
return_counts (bool, optional, default = True) – Add the size of the equivalence class to the properties associated to the representative in the collapsed hypergraph using keyword: eclass_size
return_equivalence_classes (boolean, optional, default = False) – Returns a dictionary of edge equivalence classes keyed by a representative from each class
aggregate_nodes_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries
aggregate_cells_by (dict, optional, default = {'weight':'sum'}) – dictionary of aggregation methods keyed by column names in the properties dataframes, does not apply to misc_properties. Defaults to ‘first’ on unlisted columns. See pandas.core.groupby.DataFrameGroupBy.agg for usage examples with dictionaries

Return type:

Hypergraph

Notes

Collapses the nodes of Hypergraph. Two nodes are duplicates if their respective memberships are the same. Using this as an equivalence relation, the uids of the nodes are partitioned into equivalence classes. A single member of the equivalence class is chosen to represent the class.

Example

>>> data = {'E1': ('a', 'b'), 'E2': ('a', 'b')}
>>> h = Hypergraph(data)
>>> h.incidence_dict
{'E1': ['a', 'b'], 'E2': ['a', 'b']}
>>> h.collapse_nodes().incidence_dict
{'E1': ['a'], 'E2': ['a']}
>>> h.collapse_nodes(use_counts=True).incidence_dict
{'E1: ['a:2'], 'E2': ['a:2']}
>>> h.collapse_nodes().properties.to_dict(orient='records')
[{'weight': 2.0, 'misc_properties': {}}, {'weight': 2.0, 'misc_properties': {}}]

collapse_nodes_and_edges(name=None, use_edge_uids=None, use_node_uids=None, use_counts=False, return_counts=True, return_equivalence_classes=False, aggregate_nodes_by=None, aggregate_edges_by=None, aggregate_cells_by=None)[source]

Returns a new hypergraph by collapsing nodes and edges.

Parameters:

name (str, optional, default = None)
return_equivalence_classes (boolean, optional, default = False) – Returns a dictionary of edge equivalence classes keyed by a representative from each class
use_edge_uids (list, optional, default = None) – Specify the edge and node identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_node_uids (list, optional, default = None) – Specify the edge and node identifiers to use as representatives for a single equivalence class. If two identifiers occur in the same equivalence class, the first one found will be used.
use_counts (boolean, optional, default = False) – Rename the equivalence class representatives as <uid>:<size of class>
return_counts (bool, optional, default = True) – Add the size of the equivalence class to the properties associated to the representative in the collapsed hypergraph using keyword: eclass_size
aggregate_nodes_by (optional) – default = {‘weight’ = ‘sum’}, all Method to combine duplicate rows of data for the same uids
aggregate_edges_by (optional) – default = {‘weight’ = ‘sum’}, all Method to combine duplicate rows of data for the same uids
aggregate_cells_by (optional) – default = {‘weight’ = ‘sum’}, all Method to combine duplicate rows of data for the same uids

Returns:

new hypergraph (Hypergraph)
node equivalence classes (dict)
edge equivalence classes (dict)

Notes

Collapses the Nodes and Edges of Hypergraph. Two nodes(edges) are duplicates if their respective memberships(elements) are the same. Using this as an equivalence relation, the uids of the nodes(edges) are partitioned into equivalence classes. A single member of the equivalence class is chosen to represent the class.

Example

>>> data = {'E1': ('a', 'b'), 'E2': ('a', 'b')}
>>> h = Hypergraph(data)
>>> h.incidence_dict
{'E1': ['a', 'b'], 'E2': ['a', 'b']}
>>> h.collapse_nodes_and_edges().incidence_dict
{'E1': ['a']}
>>> h.collapse_nodes_and_edges(use_counts=True).incidence_dict
{'E1:2': ['a:2']}

component_subgraphs(return_singletons=False, name=None)[source]: Same as s_components_subgraphs() with s=1. Returns iterator.

See also

s_component_subgraphs

components(edges=False)[source]: Same as s_connected_components() with s=1, but nodes are returned by default. Return iterator.

See also

s_connected_components

connected_component_subgraphs(return_singletons=True, name=None)[source]: Same as s_component_subgraphs() with s=1. Returns iterator

See also

s_component_subgraphs

connected_components(edges=False)[source]: Same as s_connected_components() with s=1, but nodes are returned by default. Return iterator.

See also

s_connected_components

property dataframe

Returns dataframe of incidence properties as dataframe with edges and nodes in columns.

Return type:: pandas.DataFrame

degree(node_uid, s=1, max_size=None)[source]

The number of edges of size at least s and at most max_size that contain the node.

Parameters:

node_uid (hashable) – Identifier for the node.
s (int, optional, default=1) – The smallest size (must be positive) of an edge to consider in degree.
max_size (int, optional, default=None) – The largest size (must be positive) of edge to consider in degree.

Returns:

The number of edges of size at least s and at most max_size that contain the node.

Return type:

int

diameter(s=1)[source]

Returns the length of the longest shortest s-walk between nodes in hypergraph

Parameters:: s (int, optional, default=1)
Returns:: diameter
Return type:: int
Raises:: HyperNetXError – If hypergraph is not s-edge-connected

Notes

Two nodes are s-adjacent if they share s edges. Two nodes v_start and v_end are s-walk connected if there is a sequence of nodes v_start, v_1, v_2, … v_n-1, v_end such that consecutive nodes are s-adjacent. If the graph is not connected, an error will be raised.

difference(other, name=None)[source]

Hypergraph obtained by restricting to incidences in self but not in other.

Parameters:

other (Hypergraph)
name (str, optional, default = None)

Return type:

Hypergraph

dim(edge)[source]

Same as size(edge) - 1()

Parameters:: edge (hashable) – The uid of an edge in the hypergraph
Return type:: int

distance(source, target, s=1)[source]

Returns the shortest s-walk distance between two nodes in the hypergraph.

Parameters:

source (str | int) – a node in the hypergraph
target (str | int) – a node in the hypergraph
s (positive int, optional, default=1) – the number of edges

Returns:

s-walk distance

Return type:

int

See also

edge_distance

Notes

The s-distance is the shortest s-walk length between the nodes. An s-walk between nodes is a sequence of nodes that pairwise share at least s edges. The length of the shortest s-walk is 1 less than the number of nodes in the path sequence.

Uses the networkx shortest_path_length method on the graph generated by the s-adjacency matrix.

dual(name=None, share_properties=True)[source]

Constructs a new hypergraph with roles of edges and nodes of hypergraph reversed.

Parameters:

name (hashable, optional, default=None)
share_properties (bool, optional, default=True) – Whether to tie the edge and node properties of objects in the dual to objects in the hypergraph. If True, a change to edge and node properties in one will be reflected in the other.

Return type:

Hypergraph

edge_adjacency_matrix(s=1, index=False)[source]

Returns the s-adjacency matrix for the dual hypergraph.

Parameters:

s (int, optional, default=1)
index (boolean, optional, default=False) – If True, returns both the adjacency matrix and an array containing the row and column index of edge_uids

Returns:

edge adjacency matrix (scipy.sparse.csr_matrix)
edge indexes (np.ndarray) – an np.ndarray containing the row and column index of edge_uids.

Notes

This is also the adjacency matrix for the line graph. Two edges are s-adjacent if they share at least s nodes.

edge_diameter(s=1)[source]

Returns the length of the longest shortest s-walk between edges in the hypergraph

Parameters:: s (int, optional, default=1)
Returns:: edge_diameter
Return type:: int
Raises:: HyperNetXError – If hypergraph is not s-edge-connected

Notes

Two edges are s-adjacent if they share s nodes. Two nodes e_start and e_end are s-walk connected if there is a sequence of edges e_start, e_1, e_2, … e_n-1, e_end such that consecutive edges are s-adjacent. If the graph is not connected, an error will be raised.

edge_diameters(s=1)[source]

Returns the edge diameters of the s_edge_connected component subgraphs in the hypergraph.

Parameters:: s (int, optional, default=1)
Returns:: maximum diameter, list of diameters, list of component – maximum diameter, list of diameters (List of edge_diameters for s-edge component subgraphs in hypergraph), list of component (List of the edge uids in the s-edge component subgraphs)
Return type:: tuple[int, list, list]

edge_distance(source, target, s=1)[source]

Returns the shortest s-walk distance between two edges in the hypergraph.

Parameters:

source (str | int) – an edge in the hypergraph
target (str | int) – an edge in the hypergraph
s (positive int, optional, default=1) – the number of intersections between pairwise consecutive edges

Returns:

s-walk distance – The shortest s-walk edge distance. A shortest s-walk is computed as a sequence of edges; the s-walk distance is the number of edges in the sequence minus 1. If no such path exists returns np.inf.

Return type:

int | float

See also

distance

Notes

The s-distance is the shortest s-walk length between the edges. An s-walk between edges is a sequence of edges such that consecutive pairwise edges intersect in at least s nodes. The length of the shortest s-walk is 1 less than the number of edges in the path sequence.

Uses the networkx shortest_path_length method on the graph generated by the s-edge_adjacency matrix.

edge_neighbors(edge, s=1)[source]

The edges in hypergraph which share s nodes(s) with edge.

Parameters:

edge (hashable) – uid for an edge in hypergraph
s (int, optional, default=1) – Minimum number of nodes shared by neighbors edge node.

Returns:

a list of edge neighbors

Return type:

list

edge_size_dist()[source]

Returns the size for each edge.

Returns:: a list of sizes of each edge.
Return type:: list

property edges

Object associated with edges.

Return type:: HypergraphView

equivalence_classes(edges=True)[source]

Returns the equivalence classes created by collapsing edges or nodes.

Parameters:: edges (bool, optional, default=True) – If True collapses edges, otherwise collapses nodes.
Returns:: A list of sets of edges or nodes
Return type:: list

classmethod from_bipartite(B, node_id=1, name=None, **kwargs)[source]

Static method creates a Hypergraph from a NetworkX bipartite graph. Still to come: capturing edge and node properties from the graph for use in the hypergraph.

Parameters:

B (nx.Graph()) – A networkx bipartite graph. Each node in the graph has a property ‘bipartite’ taking the value of 0 or 1 indicating a 2-coloring of the graph.
node_id (int) – bipartite value assigned to graph nodes that will be hypergraph edges
name (hashable, optional)

Return type:

Hypergraph

Notes

A partition for the nodes in a bipartite graph generates a hypergraph.

>>> import networkx as nx
>>> B = nx.Graph()
>>> B.add_nodes_from([1, 2, 3, 4], bipartite=0)
>>> B.add_nodes_from(['a', 'b', 'c'], bipartite=1)
>>> B.add_edges_from([(1, 'a'), (1, 'b'), (2, 'b'), (2, 'c'), (3, 'c'), (4, 'a')])
>>> H = Hypergraph.from_bipartite(B, nodes=1)
>>> list(H.nodes), list(H.edges)
(['a', 'b', 'c'], [1, 2, 3, 4])

classmethod from_incidence_dataframe(df, name=None, fillna=0, key=None, return_only_dataframe=False, **kwargs)[source]

Create a hypergraph from a Pandas Dataframe object, which has values equal to the incidence matrix of a hypergraph. Its index will identify the nodes and its columns will identify its edges.

Parameters:

df (Pandas.Dataframe) – a real valued dataframe with a single index
name ((optional) string, default = None)
fillna (float, default = 0) – a real value to place in empty cell, all-zero columns will not generate an edge.
key ((optional) function, default = None) – boolean function to be applied to dataframe. will be applied to entire dataframe.
return_only_dataframe ((optional) bool, default = False) – to use the incidence_dataframe with cell_properties or properties, set this to true and use it as the setsystem in the Hypergraph constructor.

See also

from_numpy_array

Return type:: Hypergraph | pd.DataFrame

classmethod from_incidence_matrix(M, name=None, **kwargs)[source]: Accepts numpy.matrix or scipy.sparse matrix

classmethod from_numpy_array(M, node_names=None, edge_names=None, name=None, key=None, **kwargs)[source]

Create a hypergraph from a real valued matrix represented as a 2 dimensional numpy array. The matrix is converted to a matrix of 0’s and 1’s so that any truthy cells are converted to 1’s and all others to 0’s.

Parameters:

M (real valued array-like object, 2 dimensions) – representing a real valued matrix with rows corresponding to nodes and columns to edges
node_names (object, array-like, default=None) – List of node names must be the same length as M.shape[0]. If None then the node names correspond to row indices with ‘v’ prepended.
edge_names (object, array-like, default=None) – List of edge names must have the same length as M.shape[1]. If None then the edge names correspond to column indices with ‘e’ prepended.
name (hashable)
key ((optional) function) – boolean function to be evaluated on each cell of the array, must be applicable to numpy.array

Return type:

Hypergraph

Note

The constructor does not generate empty edges. All zero columns in M are removed and the names corresponding to these edges are discarded.

get_cell_properties(edge_uid, node_uid, prop_name=None)[source]

Get cell properties on a specified edge and node

Parameters:

edge_uid (str | int) – edge_uid
node_uid (str | int) – node_uid
prop_name (str, optional, default=None) – name of a cell property; if None, all cell properties will be returned

Returns:

cell property value if prop_name is provided, otherwise dict of all cell properties and values

Return type:

Any

get_linegraph(s=1, edges=True)[source]

Creates an s-linegraph for the Hypergraph. If edges=True, then the edges will be the vertices of the line graph. Two vertices are connected by an s-line-graph edge if the corresponding hypergraph edges intersect in at least s hypergraph nodes. If edges=False, the hypergraph nodes will be the vertices of the line graph. Two vertices are connected if the nodes they correspond to share at least s incident (hyper)edges.

Parameters:

s (int) – The width of the connections.
edges (bool, optional, default = True) – Determine if edges or nodes will be the vertices in the linegraph.

Returns:

A NetworkX graph.

Return type:

nx.Graph

get_properties(uid, level=0, prop_name=None)[source]

Returns an object’s specific property or all properties

Parameters:

uid (hashable) – edge or node id
level (int | None , optional, default=0) – Enter 0 for edges and 1 for nodes.
prop_name (str | None, optional, default=None) – if None then all properties associated with the object will be returned.

Returns:

single property or dictionary of properties

Return type:

Any

incidence_dataframe(weights=False)[source]

property incidence_dict

Dictionary keyed by edge uids with values as the uids of nodes of each edge

Return type:: dict

incidence_matrix(index=False, weights=False)[source]

A sparse matrix indicating the existence of an incidence pair in the hypergraph. Each row corresponds to a node v and each column corresponds to an edge e. The entry corresponding to (row v, col e) is nonzero if v is an element of e. If weights = True then the value equals the weight given in the hypergraph incidence properties for the incidence pair (e,v). Otherwise, the value is 1.

Parameters:

index (bool, optional, default = False) – If index=True, returns a tuple containing the incidence matrix, an np.ndarray containing the row and column index of node_uids, and an np.ndarray containing the row and column index of edge_uids. Otherwise, returns the incidence matrix.
weights (bool, optional, default = False) – If True, use the incidence weights corresponding to the row and column of the entry.

Returns:

incidence matrix (scipy.sparse.csr_matrix)
node indexes (np.ndarray) – an np.ndarray containing the row and column index of node_uids
edge indexes (np.ndarray) – an np.ndarray containing the row and column index of edge_uids

property incidences

Object associated with incidence pairs

Return type:: HypergraphView

intersection(other, name=None)[source]

Returns a hypergraph created by restricting to incidence pairs contained in both self and other. Properties inherited from self.

Parameters:

other (Hypergraph)
name (str, optional, default=None)

Return type:

Hypergraph

is_connected(s=1, edges=False)[source]

Determines if hypergraph is s-connected.

Parameters:

s (int, optional, default=1)
edges (boolean, optional, default=False) – If True, will determine if s-edge-connected. For s=1 s-edge-connected is the same as s-connected.

Returns:

is_connected

Return type:

boolean

Notes

A hypergraph is s node connected if for any two nodes v0,vn there exists a sequence of nodes v0,v1,v2,…,v(n-1),vn such that every consecutive pair of nodes v(i),v(i+1) share at least s edges.

A hypergraph is s edge connected if for any two edges e0,en there exists a sequence of edges e0,e1,e2,…,e(n-1),en such that every consecutive pair of edges e(i),e(i+1) share at least s nodes.

neighbors(node, s=1)[source]

The nodes in hypergraph which share s edge(s) with node.

Parameters:

node (hashable) – uid for a node in hypergraph
s (int, optional, default=1) – Minimum number of edges shared by neighbors with node.

Returns:

neighbors – s-neighbors share at least s edges in the hypergraph

Return type:

list

node_diameters(s=1)[source]

Returns the node diameters of the connected components in the hypergraph.

Parameters:: s (int, optional, default=1)
Returns:: maximum diameter, list of diameters, list of component – maximum diameter, list of diameters (List of node_diameters for s-node component subgraphs in hypergraph), list of component (List of the node uids in the s-node component subgraphs)
Return type:: tuple[int, list, list]

property nodes

Object associated with nodes.

Return type:: HypergraphView

order()[source]

The number of nodes in hypergraph.

Returns:: order
Return type:: int

property properties

Returns incidence properties

Return type:: pandas.DataFrame

remove_edges(edge_uids, name=None, inplace=True)[source]

Removes the edges from the Hypergraph. If inplace=True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Parameters:

edge_uids (str | int | list[str | int]) – edge_uids
name (str, optional, default=None) – The name of the new Hypergraph. Used only when inplace=False; ignored if inplace=True.
inplace (bool, optional, default=True) – Whether to replace the current hypergraph with a new one.

Return type:

Hypergraph

remove_incidences(incidence_uids, name=None, inplace=True)[source]

Removes the incidences from the Hypergraph. If inplace=True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Parameters:

incidence_uids (tuple[str | int] | list[tuple[str | int]]) – incidence_uids
name (str, optional, default=None) – The name of the new Hypergraph. Used only when inplace=False; ignored if inplace=True.
inplace (bool, optional, default=True) – Whether to replace the current hypergraph with a new one.

Return type:

Hypergraph

remove_nodes(node_uids, name=None, inplace=True)[source]

Removes the nodes from the Hypergraph. If inplace=True, changes the existing Hypergraph. Otherwise, creates a new Hypergraph with the requested changes.

Parameters:

node_uids (str | int | list[str | int]) – node_uids
name (str, optional, default=None) – The name of the new Hypergraph. Used only when inplace=False; ignored if inplace=True.
inplace (bool, optional, default=True) – Whether to replace the current hypergraph with a new one.

Return type:

Hypergraph

remove_singletons(name=None)[source]

Constructs clone of hypergraph with singleton edges removed.

Parameters:: name (str, optional, default=None)
Return type:: Hypergraph

rename(edges=None, nodes=None, name=None, inplace=True)[source]

Rename the edges and/or nodes of the hypergraph.

Parameters:

edges (dict, optional, default = None) – dictionary of replacement edge_uids
nodes (dict, optional, default = None) – dictionary of replacement node_uids
name (str, optional, default=None)
inplace (bool, optional, default=True)

Return type:

Hypergraph

restrict_to_edges(edges, name=None)[source]

New hypergraph gotten by restricting to edges

Parameters:

edges (Iterable) – edge identifiers to restrict to
name (str | int, optional, default=None) – edge identifier

Return type:

Hypergraph

restrict_to_nodes(nodes, name=None)[source]

New hypergraph gotten by restricting to nodes

Parameters:

nodes (Iterable) – node identifiers to restrict to
name (str | int, optional, default=None) – node identifier

Return type:

Hypergraph

s_component_subgraphs(s=1, edges=True, return_singletons=False, name=None)[source]

Returns a generator for the induced subgraphs of s_connected components. Removes singletons unless return_singletons is set to True. Computed using s-linegraph generated either by the hypergraph (edges=True) or its dual (edges = False)

Parameters:

s (int, optional, default=1)
edges (boolean, optional, default=False) – Determines if edge or node components are desired. Returns subgraphs equal to the hypergraph restricted to each set of nodes(edges) in the s-connected components or s-edge-connected components
return_singletons (bool, optional, default=False) – If True, keep singletons in subgraph. Otherwise, remove singletons.
name (str, optional, default=None)

Yields:

s_component_subgraphs (iterator) – Iterator returns subgraphs generated by the edges (or nodes) in the s-edge(node) components of hypergraph.

s_components(s=1, edges=True, return_singletons=True)[source]: Same as s_connected_components()

See also

s_connected_components

s_connected_components(s=1, edges=True, return_singletons=False)[source]

Returns a generator for the s-edge-connected component or the s-node-connected component of the hypergraph.

Parameters:

s (int, optional, default=1)
edges (boolean, optional, default=True) – If True, return edge components; otherwise, return node components
return_singletons (bool, optional, default=False) – If True, keep singletons. Otherwise, remove singletons

Notes

If edges=True, this method returns the s-edge-connected components as lists of lists of edge uids. An s-edge-component has the property that for any two edges e1 and e2 there is a sequence of edges starting with e1 and ending with e2 such that pairwise adjacent edges in the sequence intersect in at least s nodes. If s=1 these are the path components of the hypergraph.

If edges=False this method returns s-node-connected components. A list of sets of uids of the nodes which are s-walk connected. Two nodes v1 and v2 are s-walk-connected if there is a sequence of nodes starting with v1 and ending with v2 such that pairwise adjacent nodes in the sequence share s edges. If s=1 these are the path components of the hypergraph.

Example

>>> S = {'A':{1,2,3},'B':{2,3,4},'C':{5,6},'D':{6}}
>>> H = Hypergraph(S)

>>> list(H.s_connected_components(edges=True))
[{'C', 'D'}, {'A', 'B'}]
>>> list(H.s_connected_components(edges=False))
[{1, 2, 3, 4}, {5, 6}]

Yields:: s_connected_components (iterator) – Iterator returns sets of uids of the edges (or nodes) in the s-edge(node) components of hypergraph.

set_state(**kwargs)[source]

Allow state_dict updates from outside of class. Use with caution.

Parameters:: **kwargs (dict, optional) – key-value pairs to save in state dictionary

property shape

The number of nodes, number of edges

Returns:: number of nodes, number of edges
Return type:: tuple

singletons()[source]

Returns a list of singleton edges. A singleton edge is an edge of size 1 with a node of degree 1.

Returns:: singles – A list of edge uids.
Return type:: list

size(edge, nodeset=None)[source]

The number of nodes in nodeset that belong to edge. If nodeset is None then returns the size of edge

Parameters:: edge (hashable) – The uid of an edge in the hypergraph
Returns:: size
Return type:: int

sum(other, name=None)[source]

Hypergraph obtained by joining incidences from self and other. Removes duplicates and uses properties of self.

Parameters:: other (Hypergraph)
Return type:: Hypergraph

toplexes(return_hyp=False)[source]

Computes a maximal collection of toplexes for the hypergraph. A toplex is a hyperedge, which is not contained in any other hyperedge. If return_hyp=True, then returns the simple hypergraph created by restricting to the toplexes.

Parameters:: return_hyp (bool, optional, default=False)
Return type:: Hypergraph | list

union(other, name=None)[source]

The hypergraph gotten by joining incidence pairs contained in self and other. Duplicates removed. Properties inherited from self. Same as sum()

Parameters:

other (Hypergraph)
name (str, optional, default=None)

Return type:

Hypergraph

classes.incidence_store module

class classes.incidence_store.IncidenceStore(data)[source]

Bases: object

Incidence store object that stores and accesses (multi) incidences with standard methods.

Parameters:: data (Two column pandas dataframe of edges and nodes, respectively.)

collapse_identical_elements(level, use_keys=None)[source]

property data

property dimensions

The number of distinct edges and nodes in that order

Returns:: Tuple of size two of (number of unique edges, number of unique nodes).
Return type:: tuple of ints

property edges

Returns an array of edge names from the incidence pairs

Returns:: Returns an array of edge names
Return type:: array

property elements

equivalence_classes(level=0)[source]

property memberships

neighbors(level, key)[source]

Returns elements or memberships depending on level.

Parameters:

level (int) – Level indicator for finding either elements or memberships. For level 0 (elements), returns nodes in the edge. For level 1 (memberships), returns edges containing the node.
key (int or str) – Name of node or edge depending on level.

Returns:

Elements or memberships (depending on level) of a given edge or node, respectively.

Return type:

list

property nodes

Returns an array of node names from the incidence pairs

Returns:: Returns an array of node names
Return type:: array

restrict_to(level, items, inplace=False)[source]

returns IncidenceStore of subset of incidence store restricted to pairs with items in the given level Will return with same data or deepcopy depending on inplace

Parameters:

level (int) – Level indicator for finding either elements or memberships. For level 0 (elements), returns nodes in the edge. For level 1 (memberships), returns edges containing the node.
items (list) – List of uids to be removed from level
inplace (bool, optional) – whether to replace self, by default False

Returns:

subset of incidence store given a restriction.

Return type:

list

classes.property_store module

class classes.property_store.PropertyStore(data=None, default_weight=1)[source]

Bases: object

Class for storing properties of a collection of edges, nodes, or incidences.

Properties will be stored in a pandas dataframe.

copy(deep=False)[source]

Create a copy of the PropertyStore. If deep=True, create a copy of the underlying data table. Otherwise, use the same underlying data table from the original PropertyStore

Parameters:: deep (bool, optional, default=False)
Return type:: PropertyStore

property default_properties: dict

Returns copy of default dictionary of properties

Returns:: Dictionary of properties automatically given to objects either in the property store if no user defined values have been assigned to them or objects that have not yet been added to the Property Store.
Return type:: dict

get_properties(uid) → dict[source]

Get all properties of an item

Parameters:: uid (Hashable) – uid is the index used to fetch all its properties
Returns:: Output dictionary containing all properties of the uid. {named property: property value, ..., properties: {property name: property value}}
Return type:: dict

See also

get_property, set_property

get_property(uid, prop_name) → Any[source]

Get a property of an item

Parameters:

uid (Hashable) – uid is the index used to fetch its property
prop_name (str | int) – name of the property to get

Returns:

out (Any) – value of the property
None – if property not found

See also

get_properties, set_property

property properties: DataFrame

Properties assigned to all items in the underlying data table

Returns:

a dataframe with the following columns:: uid, weight, properties, <optional props> or level, id, weight, properties, <optional props>

Return type:

pandas.DataFrame

set_defaults(defaults) → None[source]

Set default values for properties

Parameters:: defaults (dict)
Return type:: None

set_properties(uid, props) → None[source]

Parameters:

uid (Hashable) – uid is the index used to set its property
props (a dictionary containing user-defined properties)

Return type:

None

set_property(uid, prop_name, prop_val) → None[source]

Set a property of an item in the ‘properties’ collection

Parameters:

uid (Hashable) – uid is the index used to set its property
prop_name (str | int) – name of the property to set
prop_val (any) – value of the property to set

Return type:

None

classes.property_store.flatten(my_dict)[source]: Recursive method to flatten dictionary for returning properties as a dictionary instead of a Series, from https://stackoverflow.com/a/71952620

col1	col2	w	col3
e1	1	0.5	{‘name’:’related_to’}
e1	2	0.1	{“name”:”related_to”, “startdate”:”05.13.2020”}
e2	1	0.52	{“name”:”owned_by”}

col1	col2	w	col3
e1	1	0.5	{‘name’:’related_to’}
e1	2	0.1	{“name”:”related_to”, “startdate”:”05.13.2020”}
e2	1	0.52	{“name”:”owned_by”}