Bulk Operations

Bulk and structural graph operations live in annnet.core._Ops.

Use G.ops for graph-owned copy, extraction, reversal, memory, and incidence helpers. Direct imports from underscore modules follow the internal API policy.

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.	required

Returns:

Type	Description
`AnnNet`	Subgraph containing selected edges and their incident nodes.

Notes

Hyperedges are supported and retain all member nodes.

subgraph

subgraph(nodes)

Create a node-induced subgraph.

Parameters:

Name	Type	Description	Default
`nodes`	`Iterable[str]`	Node identifiers to retain.	required

Returns:

Type	Description
`AnnNet`	Subgraph containing only the specified nodes and their internal edges.

Notes

For hyperedges, all member nodes must be included to retain the edge.

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] \| None`	Node IDs to include. If None, no node filtering is applied.	`None`
`edges`	`Iterable[str] \| Iterable[int] \| None`	Edge IDs or indices to include. If None, no edge filtering is applied.	`None`

Returns:

Type	Description
`AnnNet`	Filtered subgraph.

Notes

This is a convenience method that delegates to subgraph() and edge_subgraph() internally.

merge

merge(other)

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

This is the in-place union, and it is what G |= 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, use per-slice edge weights when available.	`True`

Returns:

Type	Description
`AnnNet`	Subgraph containing the slice nodes and edges.

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 (G.ops).

Functions

hash

__hash__()

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