mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-08-29 04:26:20 +00:00
KaifAhmad1
5eefadaa7f
Replace plain markdown in every docs/reference/ file and docs/concepts.md with rich Mintlify JSX components — CardGroup, Steps, Tabs, AccordionGroup, Tip, Warning, Note, and CodeGroup — for a consistent, navigable, production-grade developer experience.
299 lines
10 KiB
Markdown
299 lines
10 KiB
Markdown
---
|
||
title: "Visualization Module"
|
||
description: "Interactive and static knowledge graph, ontology, embedding, and temporal visualization."
|
||
icon: "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
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="GraphVisualizer" icon="diagram-project">
|
||
Interactive HTML (PyVis) and static image (Matplotlib) graph rendering with layout options.
|
||
</Card>
|
||
<Card title="OntologyVisualizer" icon="sitemap">
|
||
Class hierarchy and property relationship visualization from any OntologyManager.
|
||
</Card>
|
||
<Card title="EmbeddingVisualizer" icon="vector-square">
|
||
UMAP, t-SNE, and PCA dimensionality reduction plots for embedding cluster analysis.
|
||
</Card>
|
||
<Card title="TemporalVisualizer" icon="clock">
|
||
Timeline views, animated evolution, snapshot comparison, and temporal pattern highlights.
|
||
</Card>
|
||
<Card title="DistanceVisualizer (v0.5.0)" icon="circle-nodes">
|
||
Ego-mode neighborhood views and N×N distance matrix heatmaps from Distance Intelligence.
|
||
</Card>
|
||
<Card title="AnalyticsVisualizer" icon="chart-bar">
|
||
Centrality rankings, community-colored graphs, and degree distribution histograms.
|
||
</Card>
|
||
</CardGroup>
|
||
|
||
## Quick Start
|
||
|
||
<Steps>
|
||
<Step title="Render a knowledge graph">
|
||
```python
|
||
from semantica.visualization import GraphVisualizer
|
||
|
||
viz = GraphVisualizer()
|
||
|
||
# Interactive HTML — opens in browser, supports hover and click
|
||
viz.visualize(graph, output="graph.html")
|
||
```
|
||
</Step>
|
||
<Step title="Apply layout and color options">
|
||
```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
|
||
)
|
||
```
|
||
</Step>
|
||
<Step title="Export to static formats">
|
||
```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")
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
## Visualizers
|
||
|
||
<Tabs>
|
||
<Tab title="GraphVisualizer">
|
||
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 |
|
||
</Tab>
|
||
<Tab title="OntologyVisualizer">
|
||
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")
|
||
```
|
||
</Tab>
|
||
<Tab title="EmbeddingVisualizer">
|
||
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 |
|
||
</Tab>
|
||
<Tab title="TemporalVisualizer">
|
||
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")
|
||
```
|
||
</Tab>
|
||
<Tab title="DistanceVisualizer (v0.5.0)">
|
||
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",
|
||
)
|
||
```
|
||
</Tab>
|
||
<Tab title="AnalyticsVisualizer">
|
||
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",
|
||
)
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## Color Schemes
|
||
|
||
All visualizers accept a `color_scheme` parameter:
|
||
|
||
```python
|
||
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`:
|
||
|
||
```python
|
||
from semantica.explorer import start_explorer
|
||
|
||
start_explorer(graph=kg, port=8080)
|
||
# Opens at http://localhost:8080
|
||
```
|
||
|
||
See the [Explorer reference](explorer) for the full feature set and REST API.
|
||
|
||
## Tips and Common Pitfalls
|
||
|
||
<Warning>
|
||
**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.
|
||
</Warning>
|
||
|
||
<Tip>
|
||
**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.
|
||
</Tip>
|
||
|
||
<Tip>
|
||
**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.
|
||
</Tip>
|
||
|
||
<Tip>
|
||
**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.
|
||
</Tip>
|
||
|
||
<Warning>
|
||
**`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.
|
||
</Warning>
|
||
|
||
<Tip>
|
||
**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.
|
||
</Tip>
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="Knowledge Graph" icon="diagram-project" href="kg">
|
||
The graph being visualized.
|
||
</Card>
|
||
<Card title="Ontology" icon="sitemap" href="ontology">
|
||
Visualize ontology class structure.
|
||
</Card>
|
||
<Card title="Embeddings" icon="vector-square" href="embeddings">
|
||
Generate the embeddings visualized here.
|
||
</Card>
|
||
<Card title="Explorer" icon="globe" href="explorer">
|
||
Full interactive Knowledge Explorer UI.
|
||
</Card>
|
||
</CardGroup>
|