Operations

anet.ops copies a graph, extracts a subgraph, combines graphs (union, intersection, difference), reverses edges and builds incidence matrices.

annnet.core._Ops.Operations

Topology materialization and graph-copy operations (mixed into AnnNet).

Functions

edge_subgraph

edge_subgraph(edges)

Create a subgraph containing only a specified subset of edges.

Parameters:

Name	Type	Description	Default
edges	Iterable[str] | Iterable[int]	Edge identifiers or edge indices to retain. Unknown ids are skipped.	required

Returns:

Type	Description
AnnNet	The selected edges with their full endpoint entities — a hyperedge keeps every member, an edge entity brings its backing edge — and nothing else. The same selection as anet.view(edges=edges).materialize().

subgraph

subgraph(nodes)

Create a node-induced subgraph.

Parameters:

Name	Type	Description	Default
nodes	Iterable[str | tuple]	Node identifiers, or explicit (node_id, layer) placements, to retain. A bare id keeps every placement of the node. Unknown ids are skipped.	required

Returns:

Type	Description
AnnNet	The selected nodes and every edge whose complete endpoint set is selected (a hyperedge is kept whole or dropped). The same selection as anet.view(nodes=nodes).materialize().

extract_subgraph

extract_subgraph(nodes=None, edges=None)

Create a subgraph based on node and/or edge filters.

Parameters:

Name	Type	Description	Default
nodes	Iterable[str]	Node IDs to include. If None, no node filtering is applied.	None
edges	Iterable[str] | Iterable[int]	Edge IDs or indices to include. If None, no edge filtering is applied.	None

Returns:

Type	Description
AnnNet	The same selection as anet.view(nodes=..., edges=...).materialize(): both constraints apply, with the closed boundary.

merge

merge(other)

Take every element of other that this graph does not hold.

This is the in-place union, and it is what anet |= H runs. The graph on the left is the answer wherever the two disagree: an element both graphs hold keeps the attributes it has here, and only an element this graph does not hold arrives with the attributes of other.

Parameters:

Name	Type	Description	Default
other	AnnNet	The graph to take from. It is not changed.	required

Returns:

Type	Description
AnnNet	This graph.

union

union(other)

Return a graph holding every element of this graph and of other.

Where the two disagree about one element, this graph is the answer. See :meth:merge, which is the same operation without the copy.

intersection

intersection(other)

Return a graph holding the elements that both graphs hold.

An edge survives only when every node it names does, so an edge both graphs hold is dropped when one of its endpoints is not shared.

difference

difference(other)

Return a graph holding the elements other does not hold.

An edge survives only when every node it names does, so an edge that keeps its own id loses its place when an endpoint goes.

symmetric_difference

symmetric_difference(other)

Return a graph holding the elements exactly one of the two holds.

reverse

reverse()

Return a new graph with all directed edges reversed.

Returns:

Type	Description
AnnNet	A new AnnNet instance with reversed directionality where applicable.

Behavior

• Binary edges: direction is flipped by swapping source and target.
• Directed hyperedges: head and tail sets are swapped.
• Undirected edges/hyperedges: unaffected.
• Edge attributes and metadata are preserved.

Notes

• This operation does not modify the original graph.
• If the graph is undirected (self.directed == False), the result is identical to the original.
• For mixed graphs (directed + undirected edges), only the directed ones are reversed.

subgraph_from_slice

subgraph_from_slice(
    slice_id, *, resolve_slice_weights=True
)

Create a subgraph induced by a single slice.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
resolve_slice_weights	bool	If True, an edge whose weight this slice overrides takes the override as its stored weight in the copy.	True

Returns:

Type	Description
AnnNet	The slice's recorded nodes and edges (a slice is a membership set, so no edge is induced), with that slice active.

Raises:

Type	Description
KeyError	If the slice does not exist.

copy

copy(history=False)

Deep copy of the entire AnnNet.

Parameters:

Name	Type	Description	Default
history	bool	If True, copy the mutation history and snapshot timeline. If False, the new graph starts with a clean history.	False

Returns:

Type	Description
AnnNet	A new graph with full structural and attribute fidelity.

Notes

O(N) Python, O(nnz) matrix; this path is optimized for speed.

memory_usage

memory_usage()

Approximate total memory usage in bytes.

Returns:

Type	Description
int	Estimated bytes for the incidence matrix, dictionaries, and attribute DFs.

get_node_incidence_matrix_as_lists

get_node_incidence_matrix_as_lists(values=False)

Materialize the node–edge incidence structure as Python lists.

Parameters:

Name	Type	Description	Default
values	(bool, optional(default=False))	If False, returns edge indices incident to each node. If True, returns the matrix values (usually weights or 1/0) for each incident edge instead of the indices.	False

Returns:

Type	Description
dict[str, list]	A mapping from node_id - list of incident edges (indices or values), where: - Keys are node IDs. - Values are lists of edge indices (if values=False) or numeric values from the incidence matrix (if values=True).

Notes

• Internally uses the sparse incidence matrix self._matrix, which is stored as a SciPy CSR (compressed sparse row) matrix or similar.
• The incidence matrix M is defined as:
  • Rows: nodes
  • Columns: edges
  • Entry M[i, j] non-zero ⇨ node i is incident to edge j.
• This is a convenient method when you want a native-Python structure for downstream use (e.g., exporting, iterating, or visualization).

node_incidence_matrix

node_incidence_matrix(values=False, sparse=False)

Return the node–edge incidence matrix in sparse or dense form.

Parameters:

Name	Type	Description	Default
values	(bool, optional(default=False))	If True, include the numeric values stored in the matrix (e.g., weights or signed incidence values). If False, convert the matrix to a binary mask (1 if incident, 0 if not).	False
sparse	(bool, optional(default=False))	If True, return the underlying sparse matrix (CSR). If False, return a dense NumPy ndarray.	False

Returns:

Type	Description
csr_matrix | ndarray	The node–edge incidence matrix M: - Rows correspond to nodes. - Columns correspond to edges. - M[i, j] ≠ 0 indicates that node i is incident to edge j.

Notes

• If values=False, the returned matrix is binarized before returning.
• Use sparse=True for large graphs to avoid memory blowups.
• This is the canonical low-level structure that most algorithms (e.g., spectral clustering, Laplacian construction, hypergraph analytics) rely on.

annnet.core._Ops.OperationsAccessor

Namespace for structural graph operations (anet.ops).

Functions

__hash__

__hash__()

Structural hash over nodes, edge endpoints/direction, and graph attrs.