Update visualization notebooks: temporal snapshot comparison and version history; align APIs (KGVisualizer.visualize_network, EmbeddingVisualizer.visualize_2d_projection); add semantic network and multimodal/quality examples; refresh docs references

cookbook/advanced/03_Complete_Visualization_Suite.ipynb

@@ -95,8 +95,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "kg_visualizer = KGVisualizer()\n",
-    "kg_visualizer.visualize(knowledge_graph, layout=\"spring\", show_labels=True)\n"
+    "kg_visualizer = KGVisualizer(layout=\"force\", color_scheme=\"vibrant\")\n",
+    "kg_visualizer.visualize_network(knowledge_graph, output=\"interactive\")\n"
    ]
   },
   {
@@ -119,7 +119,7 @@
     "labels = [entity.get(\"type\", \"Unknown\") for entity in entities]\n",
     "\n",
     "embedding_visualizer = EmbeddingVisualizer()\n",
-    "embedding_visualizer.visualize_tsne(embeddings, labels, title=\"Entity Embeddings Visualization\")\n"
+    "embedding_visualizer.visualize_2d_projection(embeddings, labels, method=\"tsne\", output=\"interactive\", file_path=None)\n"
    ]
   },
   {
@@ -135,11 +135,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "quality_assessor = KGQualityAssessor()\n",
-    "quality_metrics = quality_assessor.assess(knowledge_graph)\n",
-    "\n",
     "quality_visualizer = QualityVisualizer()\n",
-    "quality_visualizer.visualize_metrics(quality_metrics, title=\"Knowledge Graph Quality Metrics\")\n"
+    "quality_report = {\n",
+    "    \"overall_score\": 0.85,\n",
+    "    \"consistency_score\": 0.90,\n",
+    "    \"completeness_score\": 0.80\n",
+    "}\n",
+    "quality_visualizer.visualize_dashboard(quality_report, output=\"interactive\")\n"
    ]
   },
   {
@@ -231,9 +233,32 @@
     "    ]\n",
     "}\n",
     "\n",
+    "from semantica.kg import TemporalVersionManager\n",
     "temporal_visualizer = TemporalVisualizer()\n",
-    "temporal_visualizer.visualize_timeline(temporal_kg, title=\"Temporal Knowledge Graph Timeline\")\n",
-    "temporal_visualizer.visualize_evolution(entity_history, entity_id=\"e1\", title=\"Entity Evolution\")\n"
+    "temporal_visualizer.visualize_timeline(temporal_kg, output=\"interactive\")\n",
+    "# Convert entity history to metrics for visualization\n",
+    "timestamps = [str(item[\"timestamp\"]) for item in entity_history[\"e1\"]]\n",
+    "age_values = [item[\"properties\"][\"age\"] for item in entity_history[\"e1\"]]\n",
+    "metrics_history = {\"age\": age_values}\n",
+    "temporal_visualizer.visualize_metrics_evolution(metrics_history, timestamps, output=\"interactive\")\n",
+    "\n",
+    "# Create versions for snapshot comparison\n",
+    "version_manager = TemporalVersionManager()\n",
+    "v1 = version_manager.create_version(temporal_kg, timestamp=\"2020-01-01\", version_label=\"v2020\")\n",
+    "temporal_kg_v2 = {\n",
+    "    \"entities\": temporal_kg.get(\"entities\", []),\n",
+    "    \"relationships\": temporal_kg.get(\"relationships\", []) + [\n",
+    "        {\"source\": \"e1\", \"target\": \"e2\", \"type\": \"collaborated_with\", \"valid_from\": \"2023-01-01\"}\n",
+    "    ]\n",
+    "}\n",
+    "v2 = version_manager.create_version(temporal_kg_v2, timestamp=\"2023-01-01\", version_label=\"v2023\")\n",
+    "snapshots = {v1[\"timestamp\"]: v1, v2[\"timestamp\"]: v2}\n",
+    "temporal_visualizer.visualize_snapshot_comparison(snapshots, output=\"interactive\")\n",
+    "version_history = [\n",
+    "    {\"version\": v1.get(\"label\"), \"timestamp\": v1.get(\"timestamp\")},\n",
+    "    {\"version\": v2.get(\"label\"), \"timestamp\": v2.get(\"timestamp\")}\n",
+    "]\n",
+    "temporal_visualizer.visualize_version_history(version_history, output=\"interactive\")\n"
    ]
   },
   {

cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb

@@ -172,6 +172,52 @@
     "- **TemporalVersionManager**: Temporal versioning and snapshots\n",
     "- **TemporalVisualizer**: Temporal data visualization\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Snapshot Comparison and Version History\n",
+    "\n",
+    "Compare graph snapshots across time and visualize version history."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create multiple versions\n",
+    "version_manager = TemporalVersionManager()\n",
+    "version_2020 = version_manager.create_version(temporal_kg, timestamp=\"2020-01-01\", version_label=\"v2020\")\n",
+    "# Simulate changes for 2023\n",
+    "temporal_kg_updated = {\n",
+    "    \"entities\": temporal_kg.get(\"entities\", []),\n",
+    "    \"relationships\": temporal_kg.get(\"relationships\", []) + [\n",
+    "        {\"source\": \"e1\", \"target\": \"e2\", \"type\": \"collaborated_with\", \"valid_from\": \"2023-01-01\"}\n",
+    "    ]\n",
+    "}\n",
+    "version_2023 = version_manager.create_version(temporal_kg_updated, timestamp=\"2023-01-01\", version_label=\"v2023\")\n",
+    "\n",
+    "# Build snapshots dict for comparison\n",
+    "snapshots = {\n",
+    "    version_2020[\"timestamp\"]: version_2020,\n",
+    "    version_2023[\"timestamp\"]: version_2023\n",
+    "}\n",
+    "\n",
+    "# Visualize snapshot comparison\n",
+    "fig_snapshots = temporal_visualizer.visualize_snapshot_comparison(snapshots, output=\"interactive\")\n",
+    "\n",
+    "# Build version history list\n",
+    "version_history = [\n",
+    "    {\"version\": version_2020.get(\"label\", \"v2020\"), \"timestamp\": version_2020.get(\"timestamp\"), \"changes\": f\"Entities: {len(version_2020.get('entities', []))}, Relationships: {len(version_2020.get('relationships', []))}\"},\n",
+    "    {\"version\": version_2023.get(\"label\", \"v2023\"), \"timestamp\": version_2023.get(\"timestamp\"), \"changes\": f\"Entities: {len(version_2023.get('entities', []))}, Relationships: {len(version_2023.get('relationships', []))}\"}\n",
+    "]\n",
+    "\n",
+    "# Visualize version history\n",
+    "fig_versions = temporal_visualizer.visualize_version_history(version_history, output=\"interactive\")\n"
+   ]
   }
  ],
  "metadata": {

cookbook/introduction/16_Visualization.ipynb

@@ -118,6 +118,69 @@
     "visualization = embedding_visualizer.visualize_2d_projection(embeddings, labels, method=\"umap\")\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 4: Semantic Network Visualization\n",
+    "\n",
+    "Visualize semantic networks: structure, node types, and edge types."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from semantica.visualization import SemanticNetworkVisualizer\n",
+    "\n",
+    "semantic_network = {\n",
+    "    \"nodes\": [\n",
+    "        {\"id\": \"n1\", \"label\": \"Node 1\", \"type\": \"Entity\"},\n",
+    "        {\"id\": \"n2\", \"label\": \"Node 2\", \"type\": \"Entity\"}\n",
+    "    ],\n",
+    "    \"edges\": [\n",
+    "        {\"source\": \"n1\", \"target\": \"n2\", \"label\": \"related_to\"}\n",
+    "    ]\n",
+    "}\n",
+    "\n",
+    "sem_viz = SemanticNetworkVisualizer()\n",
+    "sem_viz.visualize_network(semantic_network, output=\"interactive\")\n",
+    "sem_viz.visualize_node_types(semantic_network, output=\"interactive\")\n",
+    "sem_viz.visualize_edge_types(semantic_network, output=\"interactive\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 5: Advanced Embedding Visualization\n",
+    "\n",
+    "Compare multi-modal embeddings and assess embedding quality."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from semantica.visualization import EmbeddingVisualizer\n",
+    "\n",
+    "# Synthetic multi-modal embeddings (text, image, audio)\n",
+    "text_emb = np.random.rand(50, 128)\n",
+    "image_emb = np.random.rand(50, 128)\n",
+    "audio_emb = np.random.rand(50, 128)\n",
+    "\n",
+    "emb_viz = EmbeddingVisualizer()\n",
+    "emb_viz.visualize_multimodal_comparison(text_emb, image_emb, audio_emb, output=\"interactive\")\n",
+    "\n",
+    "# Embedding quality metrics\n",
+    "quality_fig = emb_viz.visualize_quality_metrics(text_emb, output=\"interactive\")\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -128,7 +191,8 @@
     "\n",
     "- **KGVisualizer**: Visualize knowledge graphs\n",
     "- **OntologyVisualizer**: Visualize ontologies\n",
-    "- **EmbeddingVisualizer**: Visualize embeddings\n",
+    "- **EmbeddingVisualizer**: Visualize embeddings, multi-modal and quality metrics\n",
+    "- **SemanticNetworkVisualizer**: Visualize semantic network structure and type distributions\n",
     "\n",
     "Next: Learn how to detect conflicts in the Conflict_Detection notebook.\n"
    ]

docs/reference/visualization.md

@@ -86,7 +86,9 @@ Visualizes Knowledge Graph structure and communities.
 |--------|-------------|
 | `visualize_network(graph)` | Standard network plot |
 | `visualize_communities(graph)` | Color by community |
-| `visualize_path(path)` | Highlight specific path |
+| `visualize_centrality(graph, centrality, centrality_type)` | Size/color by centrality |
+| `visualize_entity_types(graph)` | Entity type distribution |
+| `visualize_relationship_matrix(graph)` | Relationship frequency heatmap |
 
 **Example:**
 
@@ -108,6 +110,10 @@ Visualizes schema and taxonomy.
 |--------|-------------|
 | `visualize_hierarchy(ontology)` | Tree view of classes |
 | `visualize_properties(ontology)` | Property domain/range graph |
+| `visualize_structure(ontology)` | Class-property network |
+| `visualize_class_property_matrix(ontology)` | Class vs property heatmap |
+| `visualize_metrics(ontology)` | Metrics dashboard |
+| `visualize_semantic_model(model)` | Visualize semantic model/network |
 
 ### EmbeddingVisualizer
 
@@ -117,9 +123,12 @@ Project high-dimensional vectors to 2D/3D.
 
 | Method | Description | Algorithm |
 |--------|-------------|-----------|
-| `visualize_2d(embeddings)` | 2D Scatter plot | UMAP/t-SNE |
-| `visualize_3d(embeddings)` | 3D Scatter plot | UMAP/t-SNE |
-| `visualize_clusters(embeddings)` | Colored by cluster | K-Means/DBSCAN |
+| `visualize_2d_projection(embeddings, labels, method)` | 2D Scatter plot | UMAP/t-SNE/PCA |
+| `visualize_3d_projection(embeddings, labels, method)` | 3D Scatter plot | UMAP/t-SNE/PCA |
+| `visualize_similarity_heatmap(embeddings, labels)` | Pairwise similarity | Cosine |
+| `visualize_clustering(embeddings, cluster_labels, method)` | Colored by cluster | UMAP/t-SNE/PCA |
+| `visualize_multimodal_comparison(text_emb, image_emb, audio_emb)` | Compare modalities | UMAP/PCA |
+| `visualize_quality_metrics(embeddings)` | Norms and stats | N/A |
 
 **Example:**
 
@@ -135,6 +144,47 @@ viz.visualize_2d_projection(
 )
 ```
 
+### SemanticNetworkVisualizer
+
+Visualizes semantic network structure and distributions.
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `visualize_network(semantic_network)` | Network visualization |
+| `visualize_node_types(semantic_network)` | Node type distribution |
+| `visualize_edge_types(semantic_network)` | Edge type distribution |
+
+### QualityVisualizer
+
+Visualizes data quality metrics and issues.
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `visualize_dashboard(quality_report)` | Quality metrics dashboard |
+| `visualize_score_distribution(quality_scores)` | Score histogram |
+| `visualize_issues(quality_report)` | Issues by type/severity |
+| `visualize_completeness_metrics(completeness_metrics)` | Completeness bar chart |
+| `visualize_consistency_heatmap(consistency_data)` | Consistency heatmap |
+
+### AnalyticsVisualizer
+
+Visualizes graph analytics results.
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `visualize_centrality_rankings(centrality, centrality_type, top_n)` | Top-k bar chart |
+| `visualize_community_structure(graph, communities)` | Community network |
+| `visualize_connectivity(connectivity)` | Components and sizes |
+| `visualize_degree_distribution(graph)` | Degree histogram |
+| `visualize_metrics_dashboard(metrics)` | Metrics dashboard |
+| `visualize_centrality_comparison(centrality_results, top_n)` | Grouped comparison |
+
 ### TemporalVisualizer
 
 Visualizes time-series and graph evolution.
@@ -144,18 +194,36 @@ Visualizes time-series and graph evolution.
 | Method | Description |
 |--------|-------------|
 | `visualize_timeline(events)` | Event timeline |
-| `visualize_evolution(snapshots)` | Graph changes over time |
+| `visualize_temporal_patterns(patterns)` | Pattern durations |
+| `visualize_snapshot_comparison(snapshots)` | Compare snapshots |
+| `visualize_version_history(version_history)` | Version timeline |
+| `visualize_metrics_evolution(metrics_history, timestamps)` | Metrics over time |
 
 ---
 
 ## Convenience Functions
 
 ```python
-from semantica.visualization import visualize_kg, visualize_embeddings
+from semantica.visualization import (
+    visualize_kg,
+    visualize_embeddings,
+    visualize_ontology,
+    visualize_semantic_network,
+    visualize_quality,
+    visualize_analytics,
+    visualize_temporal,
+    list_available_methods,
+)
 
 # One-line visualization
 visualize_kg(kg, output="graph.html")
 visualize_embeddings(embeddings, method="umap")
+visualize_ontology(ontology, method="hierarchy")
+visualize_semantic_network(semantic_network)
+visualize_quality(quality_report)
+visualize_analytics({"centrality": centrality}, method="centrality")
+visualize_temporal(temporal_data, method="timeline")
+list_available_methods()
 ```
 
 ---
@@ -165,9 +233,9 @@ visualize_embeddings(embeddings, method="umap")
 ### Environment Variables
 
 ```bash
-export VIZ_DEFAULT_LAYOUT=force
-export VIZ_COLOR_SCHEME=vibrant
-export VIZ_RENDERER=plotly
+export VISUALIZATION_DEFAULT_LAYOUT=force
+export VISUALIZATION_COLOR_SCHEME=vibrant
+export VISUALIZATION_OUTPUT_FORMAT=interactive
 ```
 
 ### YAML Configuration
@@ -209,7 +277,8 @@ kg_viz.visualize_network(kg, output="structure.html")
 
 # 3. Visualize Analytics
 analytics_viz = AnalyticsVisualizer()
-analytics_viz.visualize_centrality(kg, output="centrality.png")
+centrality = {"rankings": [{"node": "A", "score": 0.9}, {"node": "B", "score": 0.7}]}
+analytics_viz.visualize_centrality_rankings(centrality, centrality_type="degree", top_n=10, output="centrality.png")
 analytics_viz.visualize_degree_distribution(kg, output="degree_dist.png")
 ```
 

semantica/visualization/visualization_usage.md

@@ -951,6 +951,34 @@ viz = KGVisualizer(layout="circular", radius=1.5)
 - `visualize_similarity_heatmap(embeddings, labels, output, file_path, **options)`: Similarity heatmap
 - `visualize_clustering(embeddings, cluster_labels, method, output, file_path, **options)`: Clustering visualization
 - `visualize_multimodal_comparison(text_emb, image_emb, audio_emb, output, file_path, **options)`: Multi-modal comparison
+- `visualize_quality_metrics(embeddings, output, file_path, **options)`: Quality metrics (norms, stats)
+
+#### SemanticNetworkVisualizer Methods
+- `visualize_network(semantic_network, output, file_path, **options)`: Visualize semantic network
+- `visualize_node_types(semantic_network, output, file_path, **options)`: Node type distribution
+- `visualize_edge_types(semantic_network, output, file_path, **options)`: Edge type distribution
+
+#### QualityVisualizer Methods
+- `visualize_dashboard(quality_report, output, file_path, **options)`: Quality metrics dashboard
+- `visualize_score_distribution(quality_scores, output, file_path, **options)`: Score distribution
+- `visualize_issues(quality_report, output, file_path, **options)`: Issues by type and severity
+- `visualize_completeness_metrics(completeness_metrics, output, file_path, **options)`: Completeness metrics
+- `visualize_consistency_heatmap(consistency_data, output, file_path, **options)`: Consistency heatmap
+
+#### AnalyticsVisualizer Methods
+- `visualize_centrality_rankings(centrality, centrality_type, top_n, output, file_path, **options)`: Centrality rankings
+- `visualize_community_structure(graph, communities, output, file_path, **options)`: Community structure
+- `visualize_connectivity(connectivity, output, file_path, **options)`: Connectivity analysis
+- `visualize_degree_distribution(graph, output, file_path, **options)`: Degree distribution
+- `visualize_metrics_dashboard(metrics, output, file_path, **options)`: Metrics dashboard
+- `visualize_centrality_comparison(centrality_results, top_n, output, file_path, **options)`: Compare multiple centralities
+
+#### TemporalVisualizer Methods
+- `visualize_timeline(temporal_data, output, file_path, **options)`: Event timeline
+- `visualize_temporal_patterns(patterns, output, file_path, **options)`: Temporal patterns
+- `visualize_snapshot_comparison(snapshots, output, file_path, **options)`: Snapshot comparison
+- `visualize_version_history(version_history, output, file_path, **options)`: Version history
+- `visualize_metrics_evolution(metrics_history, timestamps, output, file_path, **options)`: Metrics over time
 
 #### Convenience Functions
 - `visualize_kg(graph, output, file_path, method, **options)`: Knowledge graph visualization wrapper