semantica/docs/reference/visualization.md

Visualization Module

Visualize knowledge graphs, embeddings, and analytics with interactive and static visualizations using multiple rendering engines.

Overview

• Graph Visualization: Interactive and static knowledge graph rendering
• Embedding Visualization: t-SNE, UMAP, PCA for high-dimensional data
• Analytics Visualization: Charts, plots, and dashboards
• Temporal Visualization: Time-series and evolution visualization
• Export Formats: HTML, PNG, SVG, PDF

---

Algorithms Used

Dimensionality Reduction

• t-SNE (t-Distributed Stochastic Neighbor Embedding): Non-linear dimensionality reduction, preserves local structure
• UMAP (Uniform Manifold Approximation and Projection): Faster than t-SNE, preserves global + local structure
• PCA (Principal Component Analysis): Linear dimensionality reduction, X_reduced = X * eigenvectors

Graph Layout Algorithms

• Force-Directed Layout: Spring-electrical model with Fruchterman-Reingold algorithm
• Hierarchical Layout: Tree-based layout with Sugiyama framework
• Circular Layout: Nodes arranged in circle, edges minimize crossings
• Kamada-Kawai: Energy-based layout minimizing edge length variance

---

Main Classes

KGVisualizer

Methods:

Method	Description	Algorithm
visualize(graph, output)	Visualize knowledge graph	Force-directed layout with PyVis/Cytoscape
render_interactive(graph)	Interactive HTML visualization	D3.js/PyVis rendering
render_static(graph, format)	Static image rendering	Graphviz/Matplotlib rendering
export(graph, filename, format)	Export visualization	Format-specific export (HTML/PNG/SVG)
customize_style(node_style, edge_style)	Customize appearance	Style application

Supported Engines:

• PyVis: Interactive HTML with physics simulation
• Cytoscape.js: Web-based graph visualization
• Graphviz: Static high-quality diagrams
• Matplotlib: Python-native plotting
• Plotly: Interactive web visualizations

Example:

from semantica.visualization import KGVisualizer

visualizer = KGVisualizer(
    engine="pyvis",  # pyvis, cytoscape, graphviz, matplotlib
    layout="force_directed",  # force_directed, hierarchical, circular
    width="100%",
    height="800px"
)

# Interactive visualization
visualizer.visualize(
    graph=kg,
    output="graph.html",
    show_physics=True,
    node_color_by="type",
    edge_width_by="weight"
)

# Static visualization
visualizer.render_static(
    graph=kg,
    format="png",
    output="graph.png",
    dpi=300
)

---

EmbeddingVisualizer

Methods:

Method	Description	Algorithm
visualize(embeddings, method)	Visualize embeddings	Dimensionality reduction + scatter plot
plot_tsne(embeddings, perplexity)	t-SNE visualization	t-SNE with configurable perplexity
plot_umap(embeddings, n_neighbors)	UMAP visualization	UMAP with neighbor parameter
plot_pca(embeddings, n_components)	PCA visualization	PCA to 2D/3D
plot_clusters(embeddings, labels)	Cluster visualization	Color-coded scatter plot

t-SNE Parameters:

• perplexity: Balance between local and global structure (5-50)
• learning_rate: Step size (10-1000)
• n_iter: Number of iterations (250-1000)

UMAP Parameters:

• n_neighbors: Local neighborhood size (2-100)
• min_dist: Minimum distance between points (0.0-0.99)
• metric: Distance metric (euclidean, cosine, manhattan)

Example:

from semantica.visualization import EmbeddingVisualizer

visualizer = EmbeddingVisualizer()

# t-SNE visualization
visualizer.plot_tsne(
    embeddings=embeddings,
    labels=labels,
    perplexity=30,
    output="tsne.html"
)

# UMAP visualization
visualizer.plot_umap(
    embeddings=embeddings,
    n_neighbors=15,
    min_dist=0.1,
    output="umap.html"
)

---

AnalyticsVisualizer

Methods:

Method	Description	Algorithm
plot_metrics(metrics)	Plot graph metrics	Bar/line charts
plot_distribution(data, bins)	Plot distributions	Histogram generation
plot_timeline(events, timeline)	Plot temporal data	Time-series visualization
create_dashboard(components)	Create dashboard	Multi-panel layout

---

Configuration

# config.yaml - Visualization Configuration

visualization:
  kg:
    engine: pyvis  # pyvis, cytoscape, graphviz, matplotlib
    layout: force_directed
    width: "100%"
    height: "800px"
    physics_enabled: true
    node_size_by: degree
    node_color_by: type
    edge_width_by: weight
    
  embeddings:
    method: umap  # tsne, umap, pca
    n_components: 2
    perplexity: 30  # for t-SNE
    n_neighbors: 15  # for UMAP
    
  export:
    format: html  # html, png, svg, pdf
    dpi: 300  # for raster formats
    transparent_background: false

---

See Also

• Knowledge Graph Module
• Embeddings Module
• Export Module