Skip to content

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.

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 vertices.
Notes

Hyperedges are supported and retain all member vertices.

subgraph 
subgraph(vertices)

Create a vertex-induced subgraph.

Parameters:

Name Type Description Default
vertices Iterable[str]

Vertex identifiers to retain.

 required

Returns:

Type Description
AnnNet

Subgraph containing only the specified vertices and their internal edges.
Notes

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

extract_subgraph 
extract_subgraph(vertices=None, edges=None)

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

Parameters:

Name Type Description Default
vertices Iterable[str] | None

Vertex IDs to include. If None, no vertex 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.

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 vertices 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_vertex_incidence_matrix_as_lists 
get_vertex_incidence_matrix_as_lists(values=False)

Materialize the vertex–edge incidence structure as Python lists.

Parameters:

Name Type Description Default
values (bool, optional(default=False))
  • If False, returns edge indices incident to each vertex.
  • 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 vertex_id - list of incident edges (indices or values), where: - Keys are vertex 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: vertices
    • Columns: edges
    • Entry M[i, j] non-zero ⇨ vertex 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).
vertex_incidence_matrix 
vertex_incidence_matrix(values=False, sparse=False)

Return the vertex–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 vertex–edge incidence matrix M: - Rows correspond to vertices. - Columns correspond to edges. - M[i, j] ≠ 0 indicates that vertex 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.

Returned by G.ops. Flat methods remain during the migration window.

Functions

__hash__ 
__hash__()

Return a stable hash representing the current graph structure and metadata.

Returns:

Type Description
int

A hash value that uniquely (within high probability) identifies the graph based on its topology and attributes.
Behavior
  • Includes the set of vertices, edges, and directedness in the hash.
  • Includes graph-level attributes (if any) to capture metadata changes.
  • Does not depend on memory addresses or internal object IDs, so the same graph serialized/deserialized or reconstructed with identical structure will produce the same hash.
Notes
  • This method enables AnnNet objects to be used in hash-based containers (like set or dict keys).
  • If the graph is mutated after hashing (e.g., vertices or edges are added or removed), the hash will no longer reflect the new state.
  • The method uses a deterministic representation: sorted vertex/edge sets ensure that ordering does not affect the hash.