Graph¶
The graph module provides GraphPair, the central
data object of the library. It holds a source and target graph and exposes
all derived representations, adjacency matrices, node-pair candidates,
edge-pair adjacency.
Algorithms access whatever format they need directly from the pair. Nothing is computed until first accessed, and each representation is computed at most once.
- class libam.graph.GraphPair(src: Graph, tar: Graph, ground_truth: tuple[ndarray, ndarray] | None = None, src_features: ndarray | None = None, tar_features: ndarray | None = None)[source]¶
A matched source/target graph pair with lazily computed data representations.
Algorithms access whatever format they need (adjacency matrix, node-pair candidates, edge-pair adjacency) via properties, representations are computed once on first access and cached.
Node features (src_features, tar_features) are optional arrays of shape [n, d]. When provided, restricted algorithms can use these structural features when they are provide. The caller is responsible for ensuring feature rows remain consistent with node indices after any permutation or re-labeling.
- src: Graph¶
- tar: Graph¶
- ground_truth: tuple[ndarray, ndarray] | None = None¶
- src_features: ndarray | None = None¶
- tar_features: ndarray | None = None¶
- classmethod from_graph(G: Graph, features: ndarray | None = None) GraphPair[source]¶
Create a graph pair from a single base graph with an identity ground truth
Both src and tar start as copies of G. Use .permute() and .add_noise() to apply transformations afterward.
- Parameters:
G – A single graph of type NetworkX.Graph to derive graph pair from
features – Features accompanying the graphs nodes.
- Returns:
- classmethod from_graphs(src: Graph, tar: Graph, ground_truth: tuple[ndarray, ndarray] | None = None, src_features: ndarray | None = None, tar_features: ndarray | None = None) GraphPair[source]¶
Create a pair from two already-constructed graphs.
- permute() GraphPair[source]¶
Derive a synthetic target by randomly permuting src node labels.
Intended use: synthetic benchmarks created via GraphPair.from_graph(G). Replaces self.tar with a permuted copy of self.src and sets self.ground_truth to the corresponding node mapping.
Warning: Logs a warning if src and tar are not the same graph, since this operation discards tar. For pairs built from two distinct real-world graphs, use shuffle_labels() instead.
Returns self to allow chaining.
- shuffle_labels() GraphPair[source]¶
Randomly relabel nodes in both src and tar to remove label-based shortcuts.
Intended use: pairs built from two distinct real-world graphs via GraphPair.from_graphs(src, tar). Applies independent random permutations to each graph’s node labels so algorithms cannot exploit coincidentally matching graph patterns. Any existing ground truth is updated to remain valid.
Warning: Logs a warning if src and tar are the same graph, since for synthetic benchmarks permute() is the appropriate operation.
Returns self for chaining.
- add_noise(source_noise: float = 0.0, target_noise: float = 0.0, refill: bool = False) GraphPair[source]¶
Remove (and optionally refill) edges from src and/or tar.
- Parameters:
source_noise – Fraction of source edges to remove.
target_noise – Fraction of target edges to remove.
refill – If True, removed edges are replaced with random ones.
Returns self for chaining.
- property src_adjacency: ndarray¶
n x n adjacency matrix for src, rows/cols ordered 0..n-1.
- property tar_adjacency: ndarray¶
n x n adjacency matrix for tar, rows/cols ordered 0..n-1.
- property L: csr_matrix¶
L[i, j] = how likely src node i aligns to tar node j (degree-based).
- Type:
Candidate match scores
- property S: csr_matrix¶
S[e1, e2] = 1 if edges e1 and e2 share a matched endpoint.
- Type:
Edge-pair adjacency over L’s non-zeros
- property li: ndarray¶
Src node indices of L’s non-zero entries.
- property lj: ndarray¶
Tar node indices of L’s non-zero entries.
- property w: ndarray¶
Weights of L’s non-zero entries.
