10. How to build graphs and graph views¶
Use this recipe when you need a graph for transductive methods or want graph-derived feature views. The steps match the CLI commands and the Python snippet uses the same specs. For a full run, see the transductive tutorial.
10.1 Problem statement¶
You want to build a similarity graph from feature vectors and optionally derive graph-based views (attribute, diffusion, structural). [1][2] Start with a simple kNN spec and refine it as you evaluate methods.
10.2 When to use¶
Use this for transductive methods that require a graph, or for graph-derived feature views. [3][2]
10.3 Steps¶
1) Define a GraphBuilderSpec (scheme, metric, weights, backend). [1]
2) Build the graph with CLI or Python. [4][5]
3) (Optional) Generate views using GraphFeaturizerSpec. [2][1]
10.4 Copy-paste example¶
Use the CLI when you want to build graphs and views from the terminal (modssc graph in src/modssc/cli/graph.py), and use Python when you want to embed graph construction in code (helpers in src/modssc/graph/construction/api.py). [4][5]
CLI (graph build):
modssc graph build --dataset toy --scheme knn --metric euclidean --k 8 --backend numpy
CLI (graph views):
modssc graph views build --dataset toy --views attr diffusion --diffusion-steps 5
Python:
import numpy as np
from modssc.graph import GraphBuilderSpec, GraphFeaturizerSpec, build_graph, graph_to_views
from modssc.graph.artifacts import NodeDataset
X = np.random.randn(50, 8).astype(np.float32)
gspec = GraphBuilderSpec(scheme="knn", metric="cosine", k=5)
G = build_graph(X, spec=gspec, seed=0, cache=False)
fspec = GraphFeaturizerSpec(views=("attr", "diffusion"), diffusion_steps=3, diffusion_alpha=0.1)
node_ds = NodeDataset(X=X, y=np.zeros((50,), dtype=np.int64), graph=G, masks={})
views = graph_to_views(node_ds, spec=fspec, seed=0, cache=False)
print(list(views.views.keys()))
Graph CLI options and specs are defined in src/modssc/cli/graph.py and src/modssc/graph/specs.py. [4][1]
10.5 Pitfalls¶
Warning
GraphBuilderSpec validation is strict; unsupported combinations (for example, backend=faiss with scheme=epsilon) raise GraphValidationError. [1][6]
Tip
The graph and views caches are managed by GraphCache and ViewsCache. Use the CLI cache commands to inspect or purge them. [7][4]