API#

Release: 0.0.1
Date: 2022-03-19

Hypergraph#

class pypergraph.Hypergraph#

Represents a generic hypergraph.

property nodes: pypergraph.NodeDataAccess[pypergraph._NodeID]#: Access the data attributes of nodes.

property edges: pypergraph.EdgeIncidenceView[pypergraph._NodeID, pypergraph._EdgeID]#

Obtain a hyperedge view of the hypergraph.

This view is useful when there are few or no parallel hyperedges.

property edge_labels: pypergraph.EdgeDataAccess[pypergraph._NodeID, pypergraph._EdgeID]#

Access the data attributes of hyperedges by label.

This view is useful when there are parallel hyperedges.

add_node(node_name, attr_dict=None)#

Add the specified node into the hypergraph.

Parameters

node_name (pypergraph._NodeID) – The node’s name. Must be hashable.
attr_dict (Optional[Mapping[str, Any]]) – Data attributes to be set for the node. May be None if no data attributes need to be set.

Notes

If the node is registered with the hypergraph already, its data attributes are updated by attr_dict.

add_nodes(*node_names)#

Add multiple nodes.

Parameters: node_names (pypergraph._NodeID) – The names of the new nodes.

add_edge(node_incidence, label=None, attr_dict=None, exception_on_inaction=False)#

Add or modify the specified hyperedge.

There are 3 outcomes of this method:

A new hyperedge is created with data attributes given by attr_dict; or
An existing hyperedge has its data attributes updated by attr_dict;
Nothing happens.

If label is None, then the following take place depending on the number of hyperedges incident on node_incidence:

== 0: A hyperedge incident on node_incidence is created with data attributes attr_dict. (1)
== 1: The hyperedge will have its data attributes updated by attr_dict. (2)
>= 2: Nothing happens. (3)

If label is not None, then the following take place:

If no hyperedge has label label, then a hyperedge incident on node_incidence is created. The hyperedge has label label and data attributes attr_dict. (1)
If there is a hyperedge with label label (and a priori exactly one), and that hyperedge is incident on node_incidence, then its data attributes are updated by attr_dict. (2)
If there is a hyperedge with label label (and a priori exactly one), and that hyperedge is incident on something other than node_incidence, nothing happens. (3)

Parameters

node_incidence (pypergraph.NodeIncidenceSet[pypergraph._NodeID]) – The edge’s node incidence. This is an annotated collection of nodes.
label (Optional[Union[pypergraph._EdgeID, AnonEdgeID]]) – None or hashable hyperedge label.
attr_dict (Optional[Mapping[str, Any]]) – Data attributes to be set for the hyperedge. May be None if no data attributes need to be set.
exception_on_inaction (bool) – Whether to raise an error if nothing would be done.

Returns

None or label of hyperedge

The hyperedge is either

the one that was newly created, or
the existing one whose data attributes were updated.

None is returned only if exception_on_inaction is False and nothing is done by the method.

Raises

ValueError – If exception_on_inaction is True and nothing would be done.

Return type

Optional[Union[pypergraph._EdgeID, AnonEdgeID]]

Notes

If a hyperedge is to be created (necessarily incident on node_incidence) and node_incidence refers to nodes which do not already exist, then those nodes will be created on the fly.

add_edges(*edges)#

Add multiple hyperedges without explicit labels.

Parameters: edges (pypergraph.NodeIncidenceSet[pypergraph._NodeID]) – The node incidences of the new hyperedges.
Return type: Sequence[Optional[Union[pypergraph._EdgeID, AnonEdgeID]]]

remove_nodes(*node_names)#

Remove nodes by name.

Parameters: node_names (pypergraph._NodeID) – The names of nodes to be removed.

Notes

Any hyperedges referring to these nodes are also removed.

remove_edges(*edge_labels)#

Remove hyperedges by label.

Parameters: edge_labels (Union[pypergraph._EdgeID, AnonEdgeID]) – The labels of hyperedges to be removed.

Notes

Any nodes to which these hyperedges refer remain in the hypergraph.

remove_parallel_edges(*node_incidence)#

Remove hyperedges by node incidence.

Parameters: node_incidence (pypergraph.NodeIncidenceSet[pypergraph._NodeID]) – The node incidences of hyperedges to be removed.

Notes

For any two parallel hyperedges, either they are both removed or they both remain in the hypergraph.

Data access#

class pypergraph.NodeDataAccess#

Access to and iteration over hypergraph nodes and data attributes.

The extent of access is determined upon instantiation and cannot be changed afterwards.

There is a mechanism to fallback to default values. This is helpful if nodes do not uniformly specify the same set of data attributes.

Additional instances with different access or different default values can be created with NodeDataAccess.data().

__iter__()#

Create an iterator over node names.

Return type: Iterator[pypergraph._NodeID]

__getitem__(node_name)#

Access underlying object or data attribute by node name.

Parameters: node_name (pypergraph._NodeID) – The name of the node to be accessed.
Raises: KeyError – If no node exists with the specified name.
Return type: Any

data(attrs='inner', default=None)#

Use different access or default values.

Parameters

attrs (Union[bool, str, Collection[str]]) –

What to access. This should take one of the following forms.

Form	Access
`"inner"`	The object underlying the node.
`True`	All data attributes can be read and modified.
`False`	All data attributes can be read but not modified.
a `str` value other than `"inner"`	The data attribute with this value as its name can be read but not modified.
a collection of `str` values	The data attributes with these values as their name can be read but not modified.

In the case where multiple attributes could be read, indexing by node name returns a map over data attributes, mapping name to value. Otherwise, indexing by node name returns directly the value for the data attribute.

default –
Specification of what to return when a node lacks a requested data attribute.

This should be a map if attrs is a collection of str values.

This is unused if attrs is any of the following: "inner", True, or False.

Returns

A new NodeDataAccess instance with the specified access and default values.

Return type

pypergraph.NodeDataAccess[pypergraph._NodeID]

class pypergraph.EdgeDataAccess#

Access to and iteration over hyperedges and data attributes.

The extent of access is determined upon instantiation and cannot be changed afterwards.

There is a mechanism to fallback to default values. This is helpful if hyperedges do not uniformly specify the same set of data attributes.

Additional instances with different access or different default values can be created with EdgeDataAccess.data().

__iter__()#

Create an iterator over hyperedge labels.

Return type: Iterator[Union[pypergraph._EdgeID, AnonEdgeID]]

__getitem__(edge_label)#

Access underlying object or data attribute by hyperedge label.

Parameters: edge_label (Union[pypergraph._EdgeID, AnonEdgeID]) – The label of the hyperedge to be accessed.
Raises: KeyError – If no hyperedge exists with the specified label.
Return type: Any

data(attrs='inner', default=None)#

Use different access or default values.

Parameters

attrs (Union[bool, str, Collection[str]]) –

What to access. This should take one of the following forms:

Form	Access
`"inner"`	The object underlying the hyperedge.
`True`	All data attributes can be read and modified.
`False`	All data attributes can be read but not modified.
a `str` value other than `"inner"`	The data attribute with this value as its name can be read but not modified.
a collection of `str` values	The data attributes with these values as their name can be read but not modified.

In the case where multiple attributes could be read, indexing by node name returns a map over data attributes, mapping name to value. Otherwise, indexing by hyperedge label returns directly the value for the data attribute.

default –
Specification of what to return when a hyperedge lacks a requested data attribute.

This should be a map if attrs is a collection of str values.

This is unused if attrs is any of the following: "inner", True, or False.

Returns

A new EdgeDataAccess instance with the specified access and default values.

Return type

pypergraph.EdgeDataAccess[pypergraph._NodeID, pypergraph._EdgeID]

Optimised for the absence of parallel hyperedges#

class pypergraph.EdgeIncidenceView#

Read-only access of hyperedge labels by node incidence.

This view is useful when there are few or no parallel hyperedges.

__iter__()#

Create an iterator over node incidence sets.

Return type: Iterator[pypergraph.NodeIncidenceSet[pypergraph._NodeID]]

__getitem__(node_incidence)#

View the hyperedge with the provided node incidence.

Parameters

node_incidence (pypergraph.NodeIncidenceSet[pypergraph._NodeID]) – The nodes with which the desired hyperedge should be incident.

Raises

KeyError – If no hyperedge exists with the specified node incidence.
KeyError – If two or more hyperedges exist with the specified node incidence.

Return type

pypergraph.SingleEdgeDataView[pypergraph._NodeID, pypergraph._EdgeID]

data(attrs='inner', default=None)#

Create an object to access hyperedge data attributes.

An EdgeDataAccess instance is created by calling EdgeDataAccess.data() with the same arguments.

Parameters

attrs (Union[bool, str, Collection[str]]) – What to access. See EdgeDataAccess.data().
default – Specification of what to return when a hyperedge lacks a requested data attribute. See EdgeDataAccess.data().

Return type

pypergraph.EdgeDataAccess[pypergraph._NodeID, pypergraph._EdgeID]

parallel_to(node_incidence)#

Return an iterable of parallel hyperedges.

Parameters: node_incidence (pypergraph.NodeIncidenceSet[pypergraph._NodeID]) – The nodes with which the parallel hyperedge should be incident.
Raises: KeyError – If no hyperedge exists with the specified node incidence.
Return type: pypergraph.ParallelEdgeView[pypergraph._NodeID, pypergraph._EdgeID]

class pypergraph.SingleEdgeDataView#

Access of data attributes for a single hyperedge.

property inner: Any#: The object underlying the hyperedge.

property label: Union[pypergraph._EdgeID, AnonEdgeID]#: The distinguishing label for the hyperedge.

property nodes: pypergraph.NodeIncidenceSet[pypergraph._NodeID]#: The nodes incident to the hyperedge.

__iter__()#

Create an iterator over the data attribute names.

Return type: Iterator[str]

__getitem__(attr_name)#

Obtain the value for a given data attribute.

Parameters: attr_name (str) – The name of the data attribute.
Raises: KeyError – If the hyperedge lacks the specified data attribute.
Return type: Any

class pypergraph.ParallelEdgeView#

An iterable over the labels of one family of parallel hyperedges.

__iter__()#

Create an iterator over the hyperedges in creation order.

Return type: Iterator[Union[pypergraph._EdgeID, AnonEdgeID]]