localvectordb.visualization.graph module

Similarity graph construction and visualisation.

localvectordb.visualization._graph.build_similarity_graph(sim_matrix: DocumentSimilarityMatrix, threshold: float = 0.3) → Dict[str, List[Dict[str, Any]]]

Build a graph structure from a similarity matrix.

Parameters:

  • sim_matrix (DocumentSimilarityMatrix) – Pairwise document similarity matrix.

  • threshold (float) – Minimum similarity for an edge to be included.

Returns:

{"nodes": [...], "edges": [...]} where each node is {"id": str, "index": int} and each edge is {"source": str, "target": str, "weight": float}.

Return type:

dict

localvectordb.visualization._graph.plot_similarity_graph(sim_matrix: DocumentSimilarityMatrix, threshold: float = 0.3, layout: str = 'spring', title: str = 'Document Similarity Graph', save_path: str | Path | None = None, figsize: tuple = (10, 8), gravity: float | None = None, spread: float | None = None, **kwargs) → Figure

Visualise documents as a similarity graph.

Nodes represent documents; edges connect documents with similarity above threshold. Edge width and opacity are proportional to similarity.

Layout uses scikit-learn MDS to avoid a networkx dependency.

Parameters:

  • sim_matrix (DocumentSimilarityMatrix) – Pairwise similarity matrix.

  • threshold (float) – Edge threshold.

  • layout (str) – "spring" (default) runs a force-directed Fruchterman-Reingold layout over the thresholded edges, which groups connected documents and pushes unconnected ones apart. "mds" instead embeds the full similarity matrix with multidimensional scaling, placing every node by its distance to every other whether or not an edge is drawn.

  • title (str) – Plot title.

  • save_path (str or Path, optional) – Save path.

  • figsize (tuple) – Figure size.

  • gravity (float, optional) – Tuning for layout="spring"; see _spring_positions(). Both trade legibility against contrast – raising them loosens a densely connected component so node labels stay readable, at the cost of how sharply connected nodes separate from unconnected ones. Ignored for layout="mds".

  • spread (float, optional) – Tuning for layout="spring"; see _spring_positions(). Both trade legibility against contrast – raising them loosens a densely connected component so node labels stay readable, at the cost of how sharply connected nodes separate from unconnected ones. Ignored for layout="mds".

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If layout is not "spring" or "mds".