semantica/docs/reference/visualization.md

title, description, icon

title	description	icon
Visualization Module	Interactive and static knowledge graph, ontology, embedding, and temporal visualization.	chart-bar

semantica.visualization renders knowledge graphs, ontologies, embedding spaces, and temporal data as interactive HTML or static images — without launching the full Explorer server.

What You Get

Interactive HTML (PyVis) and static image (Matplotlib) graph rendering with layout options. Class hierarchy and property relationship visualization from any OntologyManager. UMAP, t-SNE, and PCA dimensionality reduction plots for embedding cluster analysis. Timeline views, animated evolution, snapshot comparison, and temporal pattern highlights. Ego-mode neighborhood views and N×N distance matrix heatmaps from Distance Intelligence. Centrality rankings, community-colored graphs, and degree distribution histograms.

Quick Start

```python from semantica.visualization import GraphVisualizer

viz = GraphVisualizer()

# Interactive HTML — opens in browser, supports hover and click
viz.visualize(graph, output="graph.html")
```

```python viz.visualize( graph, output="graph.html", layout="force_directed", # "force_directed" | "hierarchical" | "circular" | "spring" node_color_by="type", # color nodes by entity type attribute edge_label="relation", # show edge relationship labels color_scheme="vibrant", # color palette — see Color Schemes section max_nodes=500, # limit rendering for large graphs ) ``` ```python # Static PNG — for reports and embedding in documents viz.visualize(graph, output="graph.png", dpi=150)

# Vector SVG — for publications and scalable diagrams
viz.visualize(graph, output="graph.svg")

# PDF — for print or compliance reports
viz.visualize(graph, output="graph.pdf")
```

Visualizers

Interactive and static knowledge graph rendering:

```python
from semantica.visualization import GraphVisualizer

viz = GraphVisualizer()

# Interactive HTML
viz.visualize(graph, output="graph.html")

# Static PNG with custom DPI
viz.visualize(graph, output="graph.png", backend="matplotlib", dpi=150)

# Display inline (Jupyter or default browser)
viz.show(graph)
```

**Layout options:**

| Layout | Description | Best For |
| ------ | ----------- | -------- |
| `force_directed` | Physics simulation — clusters emerge naturally | General graphs |
| `hierarchical` | Top-down tree layout | Taxonomies, org charts |
| `circular` | Nodes on a circle, edges as chords | Small dense graphs |
| `spring` | Spring-force layout (Fruchterman-Reingold) | Medium graphs |

Visualize class hierarchies and property relationships:

```python
from semantica.visualization import OntologyVisualizer

viz = OntologyVisualizer()

# Full ontology graph — classes, properties, and constraints
viz.visualize(ontology, output="ontology.html")

# Class hierarchy only — cleaner for large ontologies
viz.visualize_hierarchy(ontology, output="hierarchy.html")
```

Project high-dimensional embeddings into 2D for cluster analysis:

```python
from semantica.visualization import EmbeddingVisualizer

viz = EmbeddingVisualizer()

viz.visualize(
    embeddings=embeddings,
    labels=labels,
    output="embeddings.html",
    method="umap",    # "umap" | "tsne" | "pca"
)
```

| Method | Speed | Preserves | Best For |
| ------ | ----- | --------- | -------- |
| `umap` | Fast | Global + local structure | Large datasets, cluster discovery |
| `tsne` | Medium | Local structure | Tight cluster separation |
| `pca` | Very fast | Variance | Quick overview, linear structure |

Visualize how a knowledge graph changes over time:

```python
from semantica.visualization import TemporalVisualizer
from datetime import datetime

viz = TemporalVisualizer()

# Static timeline of additions and removals
viz.visualize_timeline(temporal_kg, output="timeline.html")

# Animated evolution — one frame per time step
viz.animate(temporal_kg, output="evolution.html", fps=2)

# Side-by-side snapshot comparison
snap_a = temporal_kg.at(datetime(2020, 1, 1))
snap_b = temporal_kg.at(datetime(2023, 1, 1))
viz.compare_snapshots(snap_a, snap_b, output="snapshot_diff.html")

# Pattern visualization — highlight recurring temporal patterns
viz.visualize_patterns(temporal_kg, pattern_type="recurrence", output="patterns.html")
```

Semantic neighborhood and distance matrix visualization from Distance Intelligence:

```python
from semantica.visualization import DistanceVisualizer

viz = DistanceVisualizer()

# Ego-mode: neighborhood of one node colored by distance band
viz.visualize_ego(
    graph,
    center_node="Apple Inc.",
    output="ego.html",
    radius=0.5,    # semantic distance radius
)

# N×N distance matrix heatmap
viz.visualize_distance_matrix(
    matrix=distance_matrix,
    labels=node_labels,
    output="distance_heatmap.html",
)
```

Visualize graph analytics results — centrality, communities, and degree distribution:

```python
from semantica.visualization import AnalyticsVisualizer
from semantica.kg import CentralityCalculator, CommunityDetector

calc       = CentralityCalculator()
centrality = calc.calculate_all_centrality(kg)

detector    = CommunityDetector()
communities = detector.detect_communities(kg, algorithm="louvain")

viz = AnalyticsVisualizer()

# Bar chart of top-N nodes by centrality measure
viz.visualize_centrality(centrality, metric="pagerank", top_k=20, output="centrality.html")

# Community-colored graph
viz.visualize_communities(kg, communities, output="communities.html")

# Degree distribution histogram
viz.visualize_degree_distribution(kg, output="degree_dist.html")

# Combined analytics dashboard
viz.visualize_analytics_dashboard(
    kg, centrality=centrality, communities=communities,
    output="analytics_dashboard.html",
)
```

Color Schemes

All visualizers accept a color_scheme parameter:

viz.visualize(graph, output="graph.html", color_scheme="vibrant")

Scheme	Description	Best For
default	Blue-grey palette	General use
vibrant	High-contrast, saturated colours	Presentations
pastel	Soft, muted tones	Light backgrounds
dark	Dark background with bright nodes	Dark-mode dashboards
light	White background, thin edges	Publications, print
colorblind	Okabe-Ito safe palette	Accessibility

Export Formats

Format	Interactive	Scalable	Best For
.html	Yes	N/A	Web dashboards, exploratory analysis
.png	No	No	Reports, Jupyter notebooks
.svg	No	Yes	Publications, slide decks
.pdf	No	Yes	Print, compliance exports

Graph Explorer (Full Dashboard)

For a full browser-based UI with search, path finding, and the Ontology Hub, use semantica.explorer:

from semantica.explorer import start_explorer

start_explorer(graph=kg, port=8080)
# Opens at http://localhost:8080

See the Explorer reference for the full feature set and REST API.

Tips and Common Pitfalls

**Use `max_nodes=500` for large graphs.** Force-directed layouts become unreadable and very slow above ~1,000 nodes. Limit with `max_nodes=500` or filter to a subgraph (e.g., top 100 nodes by PageRank) before visualizing. **HTML output is always the best starting point.** Interactive HTML lets you zoom, pan, hover for details, and hide node types — giving you orders of magnitude more exploratory power than a static PNG. Only export to PNG/SVG/PDF when embedding in a report. **Use `color_scheme="colorblind"` in publications and dashboards.** The Okabe-Ito palette is readable for everyone, including the ~8% of male readers who are red-green colorblind. Reserve `vibrant` for internal presentations only. **UMAP is faster than t-SNE at scale.** For embedding spaces with >5,000 points, UMAP completes in seconds; t-SNE may take minutes. Both produce good cluster separation — use UMAP for exploratory speed, t-SNE for final publication-quality plots. **`TemporalVisualizer.animate()` can produce large files.** Animated HTML files include all frames and can reach dozens of MB for long time series. Use `fps=1` or reduce the number of time steps for a manageable file size. **For interactive dashboards, prefer Explorer.** `GraphVisualizer.visualize()` generates a self-contained HTML file. `start_explorer()` gives a full live web app with search, filtering, path-finding, and REST API. Use Explorer for team exploration, Visualizer for standalone report embeds. The graph being visualized. Visualize ontology class structure. Generate the embeddings visualized here. Full interactive Knowledge Explorer UI.