From d5cb9b2d344cd17ae90ef47bd04d76df698695ab Mon Sep 17 00:00:00 2001 From: KaifAhmad1 Date: Mon, 8 Dec 2025 23:17:03 +0530 Subject: [PATCH] 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 --- .../03_Complete_Visualization_Suite.ipynb | 43 +++++++-- .../10_Temporal_Knowledge_Graphs.ipynb | 46 ++++++++++ cookbook/introduction/16_Visualization.ipynb | 66 +++++++++++++- docs/reference/visualization.md | 89 ++++++++++++++++--- .../visualization/visualization_usage.md | 28 ++++++ 5 files changed, 252 insertions(+), 20 deletions(-) diff --git a/cookbook/advanced/03_Complete_Visualization_Suite.ipynb b/cookbook/advanced/03_Complete_Visualization_Suite.ipynb index 5ce0269d..b08cb615 100644 --- a/cookbook/advanced/03_Complete_Visualization_Suite.ipynb +++ b/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" ] }, { diff --git a/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb b/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb index d5a0508e..f5699dfc 100644 --- a/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb +++ b/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": { diff --git a/cookbook/introduction/16_Visualization.ipynb b/cookbook/introduction/16_Visualization.ipynb index 698152f7..45e3182e 100644 --- a/cookbook/introduction/16_Visualization.ipynb +++ b/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" ] diff --git a/docs/reference/visualization.md b/docs/reference/visualization.md index c04d58b9..188aceec 100644 --- a/docs/reference/visualization.md +++ b/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") ``` diff --git a/semantica/visualization/visualization_usage.md b/semantica/visualization/visualization_usage.md index cb380be5..19237e7a 100644 --- a/semantica/visualization/visualization_usage.md +++ b/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