xgi.core.simplicialcomplex.SimplicialComplex

class xgi.core.simplicialcomplex.SimplicialComplex(incoming_data=None, **attr)[source]

Bases: Hypergraph

A class to represent undirected simplicial complexes.

A simplicial complex is a collection of subsets of a set of nodes or vertices. It is a pair \((V, E)\), where \(V\) is a set of elements called nodes or vertices, and \(E\) is a set whose elements are subsets of \(V\), that is, each \(e \in E\) satisfies \(e \subset V\). The elements of \(E\) are called simplices. Additionally, if a simplex is part of a simplicial complex, all its faces must be too. This makes simplicial complexes a special case of hypergraphs.

The SimplicialComplex class allows any hashable object as a node and can associate attributes to each node, simplex, or the simplicial complex itself, in the form of key/value pairs.

Parameters:

incoming_data (input simplicial complex data, optional) –
Data to initialize the simplicial complex. If None (default), an empty simplicial complex is created, i.e. one with no nodes or simplices. The data can be in the following formats:
- simplex list
- simplex dictionary
- 2-column Pandas dataframe (bipartite edges)
- Incidence matrix: numpy ndarray or scipy.sparse array
- SimplicialComplex object
- Hypergraph object
**attr (dict, optional) – Attributes to add to the simplicial complex as key, value pairs. By default, None.

See also

Hypergraph

Notes

Unique IDs are assigned to each node and simplex internally and are used to refer to them throughout.

The attr keyword arguments are added as simplicial complex attributes. To add node or simplex attributes see add_node() and add_simplex(). Methods such as add_simplex() replace Hypergraph methods such as add_edge() which here raise an error.

Examples

>>> import xgi
>>> S = xgi.SimplicialComplex([[1, 2, 3], [4], [5, 6], [6, 7, 8]])
>>> S.nodes
NodeView((1, 2, 3, 4, 5, 6, 7, 8))
>>> S.edges
EdgeView((0, 1, 2, 3, 4, 5, 6, 7, 8, 9))

Attributes

`edges`	An `EdgeView` of this network.
`nodes`	A `NodeView` of this network.
`num_edges`	The number of edges in the hypergraph.
`num_nodes`	The number of nodes in the hypergraph.
`is_frozen`	Checks whether a simplicial complex is frozen

Methods

`add_node`	Add one node with optional attributes.
`add_nodes_from`	Add multiple nodes with optional attributes.
`add_simplex`	Add a simplex to the simplicial complex, and all its subfaces that do not exist yet.
`add_simplices_from`	Add multiple edges with optional attributes.
`add_weighted_simplices_from`	Add weighted simplices in ebunch_to_add with specified weight attr
`remove_simplex_id`	Remove a simplex with a given id.
`remove_simplex_ids_from`	Remove all simplicies specified in ebunch.
`remove_node`	Remove a single node.
`remove_nodes_from`	Remove multiple nodes.
`close`	Adds all missing subfaces to the complex.
`has_simplex`	Whether a simplex appears in the simplicial complex.
`cleanup`	Removes potentially undesirable artifacts from the hypergraph.
`freeze`	Method for freezing a simplicial complex which prevents it from being modified

Inherited methods that cannot be used

`add_edge`	Deprecated in SimplicialComplex.
`add_edges_from`	Deprecated in SimplicialComplex.
`add_weighted_edges_from`	Deprecated in SimplicialComplex.
`remove_edge`	Deprecated in SimplicialComplex.
`remove_edges_from`	Deprecated in SimplicialComplex.

add_edge(edge, id=None, **attr)[source]: Deprecated in SimplicialComplex. Use add_simplex instead

add_edges_from(ebunch_to_add, max_order=None, **attr)[source]: Deprecated in SimplicialComplex. Use add_simplices_from instead

add_node_to_edge(edge, node)[source]: add_node_to_edge is not implemented in SimplicialComplex.

add_simplex(members, id=None, **attr)[source]

Add a simplex to the simplicial complex, and all its subfaces that do not exist yet.

Simplex attributes can be specified with keywords or by directly accessing the simplex’s attribute dictionary. The attributes do not propagate to the subfaces.

Parameters:

members (Iterable) – An iterable of the ids of the nodes contained in the new simplex.
id (hashable, optional) – Id of the new simplex. If None (default), a unique numeric ID will be created.
**attr (dict, optional) – Attributes of the new simplex.

Raises:

XGIError – If members is empty.

See also

add_simplices_from: Add a collection of simplices.

Notes

Currently cannot add empty simplices.

Examples

Add simplices with or without specifying an simplex id.

>>> import xgi
>>> S = xgi.SimplicialComplex()
>>> S.add_simplex([1, 2, 3])
>>> S.edges.members() 
[frozenset({1, 2, 3}), frozenset({2, 3}),
    frozenset({1, 2}), frozenset({1, 3})]
>>> S.add_simplex([3, 4], id='myedge')
>>> S.edges
EdgeView((0, 1, 2, 3, 'myedge'))

Access attributes using square brackets. By default no attributes are created.

>>> S.edges[0]
{}
>>> S.add_simplex([1, 4], color='red', place='peru')
>>> S.edges
EdgeView((0, 1, 2, 3, 'myedge', 4))
>>> S.edges[4]
{'color': 'red', 'place': 'peru'}

add_simplices_from(ebunch_to_add, max_order=None, **attr)[source]

Add multiple edges with optional attributes.

Parameters:

ebunch_to_add (Iterable) –
An iterable of simplices. This may be an iterable of iterables (Format 1), where each element contains the members of the simplex specified as valid node IDs. Alternatively, each element could also be a tuple in any of the following formats:
- Format 2: 2-tuple (members, simplex_id), or
- Format 3: 2-tuple (members, attr), or
- Format 4: 3-tuple (members, simplex_id, attr),
where members is an iterable of node IDs, simplex_id is a hashable to use as simplex ID, and attr is a dict of attributes. Finally, ebunch_to_add may be a dict of the form {simplex_id: simplex_members} (Format 5).

Formats 2 and 3 are unambiguous because attr dicts are not hashable, while id`s must be. In Formats 2-4, each element of `ebunch_to_add must have the same length, i.e. you cannot mix different formats. The iterables containing simplex members cannot be strings.
max_order (int, optional) – Maximal dimension of simplices to add. If None (default), adds all simplices. If int, and ebunch_to_add contains simplices of order > max_order, creates and adds all its subfaces up to max_order.
attr (**kwargs, optional) – Additional attributes to be assigned to all simplices. Attribues specified via ebunch_to_add take precedence over attr.

See also

add_simplex: add a single simplex
add_weighted_simplices_from: convenient way to add weighted simplices

Notes

Adding the same simplex twice will add it only once. Currently cannot add empty simplices; the method skips over them.

Examples

>>> import xgi
>>> S = xgi.SimplicialComplex()

When specifying simplices by their members only, numeric simplex IDs will be assigned automatically.

>>> S.add_simplices_from([[0, 1], [1, 2], [2, 3, 4]])
>>> S.edges.members(dtype=dict) 
{0: frozenset({0, 1}), 1: frozenset({1, 2}), 2: frozenset({2, 3, 4}), 3: frozenset({2, 3}), 4: frozenset({2, 4}), 5: frozenset({3, 4})}

Custom simplex ids can be specified using a dict.

>>> S = xgi.SimplicialComplex()
>>> S.add_simplices_from({'one': [0, 1], 'two': [1, 2], 'three': [2, 3, 4]})
>>> S.edges.members(dtype=dict) 
{'one': frozenset({0, 1}), 'two': frozenset({1, 2}), 'three': frozenset({2, 3, 4}), 0: frozenset({2, 3}), 1: frozenset({2, 4}), 2: frozenset({3, 4})}

You can use the dict format to easily add simplices from another simplicial complex.

>>> S2 = xgi.SimplicialComplex()
>>> S2.add_simplices_from(S.edges.members(dtype=dict))
>>> list(S.edges) == list(S2.edges)
True

Alternatively, simplex ids can be specified using an iterable of 2-tuples.

>>> S = xgi.SimplicialComplex()
>>> S.add_simplices_from([([0, 1], 'one'), ([1, 2], 'two'), ([2, 3, 4], 'three')])
>>> S.edges.members(dtype=dict) 
{'one': frozenset({0, 1}), 'two': frozenset({1, 2}), 'three': frozenset({2, 3, 4}), 0: frozenset({2, 3}), 1: frozenset({2, 4}), 2: frozenset({3, 4})}

Attributes for each simplex may be specified using a 2-tuple for each simplex. Numeric IDs will be assigned automatically.

>>> S = xgi.SimplicialComplex()
>>> simplices = [
...     ([0, 1], {'color': 'red'}),
...     ([1, 2], {'age': 30}),
...     ([2, 3, 4], {'color': 'blue', 'age': 40}),
... ]
>>> S.add_simplices_from(simplices)
>>> {e: S.edges[e] for e in S.edges}
{0: {'color': 'red'}, 1: {'age': 30}, 2: {'color': 'blue', 'age': 40}, 3: {}, 4: {}, 5: {}}

Attributes and custom IDs may be specified using a 3-tuple for each simplex.

>>> S = xgi.SimplicialComplex()
>>> simplices = [
...     ([0, 1], 'one', {'color': 'red'}),
...     ([1, 2], 'two', {'age': 30}),
...     ([2, 3, 4], 'three', {'color': 'blue', 'age': 40}),
... ]
>>> S.add_simplices_from(simplices)
>>> {e: S.edges[e] for e in S.edges}
{'one': {'color': 'red'}, 'two': {'age': 30}, 'three': {'color': 'blue', 'age': 40}, 0: {}, 1: {}, 2: {}}

add_weighted_edges_from(ebunch_to_add, max_order=None, weight='weight', **attr)[source]: Deprecated in SimplicialComplex. Use add_weighted_simplices_from instead

add_weighted_simplices_from(ebunch_to_add, max_order=None, weight='weight', **attr)[source]

Add weighted simplices in ebunch_to_add with specified weight attr

Parameters:

ebunch_to_add (iterable of simplices) – Each simplex given in the list or container will be added to the graph. The simplices must be given as tuples of the form (node1, node2, …, noden, weight).
max_order (int, optional) – The maximum order simplex to add, by default None.
weight (string, optional) – The attribute name for the simplex weights to be added. By default, “weight”.
attr (keyword arguments, optional (default= no attributes)) – simplex attributes to add/update for all simplices.

See also

add_simplex: add a single simplex
add_simplices_from: add multiple simplices

Notes

Adding the same simplex twice will add it only once.

Example

>>> import xgi
>>> S = xgi.SimplicialComplex()
>>> simplices = [(0, 1, 0.3), (0, 2, 0.8)]
>>> S.add_weighted_simplices_from(simplices)
>>> S.edges[0]
{'weight': 0.3}

cleanup(isolates=False, connected=True, relabel=True, in_place=True)[source]

Removes potentially undesirable artifacts from the hypergraph.

Parameters:

isolates (bool, optional) – Whether isolated nodes are allowed, by default False.
singletons (bool, optional) – Whether singleton edges are allowed, by default False.
multiedges (bool, optional) – Whether multiedges are allowed, by default False.
connected (bool, optional) – Whether the returned hypergraph should be connected. If true, returns the hypergraph induced on the largest connected component. By default, False.
relabel (bool, optional) – Whether to convert all node and edge labels to sequential integers, by default True.
in_place (bool, optional) – Whether to modify the current hypergraph or output a new one, by default True.

close()[source]

Adds all missing subfaces to the complex.

See also

add_simplex: add a single simplex
add_weighted_simplices_from: convenient way to add weighted simplices

Notes

Adding the same simplex twice will add it only once. Currently cannot add empty simplices; the method skips over them.

copy()[source]

A deep copy of the simplicial complex.

A deep copy of the simplicial complex, including node, edge, and network attributes.

Returns:: S – A copy of the simplicial complex.
Return type:: SimplicialComplex

freeze()[source]

Method for freezing a simplicial complex which prevents it from being modified

See also

frozen: Method that raises an error when a

user

is_frozen: Check whether a simplicial complex is frozen

Examples

>>> import xgi
>>> edges = [[1, 2], [2, 3, 4]]
>>> S = xgi.SimplicialComplex(edges)
>>> S.freeze()
>>> S.add_node(5)
Traceback (most recent call last):
xgi.exception.XGIError: Frozen higher-order network can't be modified

has_simplex(simplex)[source]

Whether a simplex appears in the simplicial complex.

Parameters:: simplex (list or set) – An iterable of hashables that specifies an simplex
Returns:: Whether or not simplex is as a simplex in the simplicial complex.
Return type:: bool

Examples

>>> import xgi
>>> S = xgi.SimplicialComplex([[1, 2], [2, 3, 4]])
>>> S.has_simplex([1, 2])
True
>>> S.has_simplex({1, 3})
False

property is_frozen

Checks whether a simplicial complex is frozen

Returns:: True if simplicial complex is frozen, false if not.
Return type:: bool

See also

freeze: A method to prevent a simplicial complex from being modified.

Examples

>>> import xgi
>>> edges = [[1, 2], [2, 3, 4]]
>>> S = xgi.SimplicialComplex(edges)
>>> S.freeze()
>>> S.is_frozen
True

remove_edge(id)[source]: Deprecated in SimplicialComplex. Use remove_simplex_id instead

remove_edges_from(ebunch)[source]: Deprecated in SimplicialComplex. Use remove_simplex_ids_from instead

remove_node(n)[source]

Remove a single node.

The removal is strong meaning that all edges containing the node are removed.

Parameters:: n (node) – A node in the simplicial complex
Raises:: XGIError – If n is not in the simplicial complex.

See also

remove_nodes_from

remove_nodes_from(nodes)[source]

Remove multiple nodes.

Parameters:: nodes (iterable) – An iterable of nodes.

See also

remove_node

remove_simplex_id(id)[source]

Remove a simplex with a given id.

This also removes all simplices of which this simplex is face, to preserve the simplicial complex structure.

Parameters:: id (Hashable) – edge ID to remove
Raises:: XGIError – If no edge has that ID.

See also

remove_edges_from: remove a collection of edges

remove_simplex_ids_from(ebunch)[source]

Remove all simplicies specified in ebunch.

Parameters:: ebunch (list or iterable of hashables) – Each edge id given in the list or iterable will be removed from the Simplicialcomplex.
Raises:: xgi.exception.IDNotFound – If an id in ebunch is not part of the network.

See also

remove_simplex_id: remove a single simplex by ID.