Skip to content

Cache and Operations

Cache and execution helpers from annnet.core._Cache.

annnet.core._Cache.CacheManager

Cache manager for materialized views (CSR/CSC).

Attributes

csr property

Return the CSR (Compressed Sparse Row) matrix.

Returns:

Type Description
csr_matrix
Notes

Built and cached on first access.

csc property

Return the CSC (Compressed Sparse Column) matrix.

Returns:

Type Description
csc_matrix
Notes

Built and cached on first access.

adjacency property

Return the adjacency matrix computed from incidence.

Returns:

Type Description
spmatrix
Notes

For incidence matrix B, adjacency is computed as A = B @ B.T.

Functions

has_csr()

Check whether a valid CSR cache exists.

Returns:

Type Description
bool
has_csc()

Check whether a valid CSC cache exists.

Returns:

Type Description
bool
has_adjacency()

Check whether a valid adjacency cache exists.

Returns:

Type Description
bool
get_csr()

Return the cached CSR matrix.

Returns:

Type Description
csr_matrix
get_csc()

Return the cached CSC matrix.

Returns:

Type Description
csc_matrix
get_adjacency()

Return the cached adjacency matrix.

Returns:

Type Description
spmatrix
invalidate(formats=None)

Invalidate cached formats.

Parameters:

Name Type Description Default
formats list[str]

Formats to invalidate ('csr', 'csc', 'adjacency'). If None, invalidate all.

 None

Returns:

Type Description
None
build(formats=None)

Pre-build specified formats (eager caching).

Parameters:

Name Type Description Default
formats list[str]

Formats to build ('csr', 'csc', 'adjacency'). If None, build all.

 None

Returns:

Type Description
None
clear()

Clear all caches.

Returns:

Type Description
None
info()

Get cache status and memory usage.

Returns:

Type Description
dict

Status and size information for each cached format.

annnet.core._Cache.Operations

Functions

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(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(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()

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(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(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()

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(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(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.
__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.