semantica/cookbook/introduction/10_Graph_Analytics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/semantica-agi/semantica/blob/main/cookbook/introduction/11_Graph_Analytics.ipynb)\n",
    "\n",
    "# Graph Analytics\n",
    "\n",
    "## Overview\n",
    "\n",
    "This notebook demonstrates how to analyze knowledge graphs using Semantica's analytics modules. You'll learn to use `GraphAnalyzer`, `CentralityCalculator`, `CommunityDetector`, and `ConnectivityAnalyzer` to understand graph structure and properties.\n",
    "\n",
    "\n",
    "**Documentation**: [API Reference](https://semantica.readthedocs.io/reference/kg/)\n",
    "\n",
    "### Learning Objectives\n",
    "\n",
    "- Use `GraphAnalyzer` for comprehensive graph analysis\n",
    "- Use `CentralityCalculator` to compute centrality measures\n",
    "- Use `CommunityDetector` to find communities in graphs\n",
    "- Use `ConnectivityAnalyzer` to analyze graph connectivity\n",
    "\n",
    "## Installation\n",
    "\n",
    "Install Semantica from PyPI:\n",
    "\n",
    "```bash\n",
    "pip install semantica\n",
    "# Or with all optional dependencies:\n",
    "pip install semantica[all]\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "## Step 1: Graph Analysis\n",
    "\n",
    "Analyze graph structure and properties.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install semantica"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import GraphBuilder, GraphAnalyzer\n",
    "from semantica.semantic_extract import NERExtractor, RelationExtractor\n",
    "\n",
    "builder = GraphBuilder()\n",
    "analyzer = GraphAnalyzer()\n",
    "\n",
    "entities = [\n",
    "    {\"id\": \"e1\", \"type\": \"Organization\", \"name\": \"Apple Inc.\", \"properties\": {}},\n",
    "    {\"id\": \"e2\", \"type\": \"Person\", \"name\": \"Tim Cook\", \"properties\": {}},\n",
    "    {\"id\": \"e3\", \"type\": \"Location\", \"name\": \"Cupertino\", \"properties\": {}}\n",
    "]\n",
    "\n",
    "relationships = [\n",
    "    {\"source\": \"e2\", \"target\": \"e1\", \"type\": \"CEO_of\", \"properties\": {}},\n",
    "    {\"source\": \"e1\", \"target\": \"e3\", \"type\": \"located_in\", \"properties\": {}}\n",
    "]\n",
    "\n",
    "kg = builder.build(entities, relationships)\n",
    "\n",
    "metrics = analyzer.compute_metrics(kg)\n",
    "\n",
    "print(f\"Graph metrics:\")\n",
    "print(f\"  Entities: {metrics.get('entity_count', 0)}\")\n",
    "print(f\"  Relationships: {metrics.get('relationship_count', 0)}\")\n",
    "print(f\"  Density: {metrics.get('density', 0):.3f}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Centrality Measures\n",
    "\n",
    "Calculate centrality measures for entities.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import CentralityCalculator\n",
    "\n",
    "centrality_calculator = CentralityCalculator()\n",
    "\n",
    "centrality_result = centrality_calculator.calculate_degree_centrality(kg)\n",
    "centrality_scores = centrality_result.get('centrality', {})\n",
    "\n",
    "print(f\"Centrality scores:\")\n",
    "for entity_id, score in list(centrality_scores.items())[:5]:\n",
    "    print(f\"  {entity_id}: {score:.3f}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Community Detection\n",
    "\n",
    "Detect communities in the graph.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import CommunityDetector\n",
    "\n",
    "community_detector = CommunityDetector()\n",
    "\n",
    "# Get detection result\n",
    "result = community_detector.detect_communities(kg)\n",
    "\n",
    "# Extract communities list from result dictionary\n",
    "communities = result.get(\"communities\", [])\n",
    "\n",
    "print(f\"Detected {len(communities)} communities\")\n",
    "for i, community in enumerate(communities[:3], 1):\n",
    "    print(f\"  Community {i}: {len(community)} entities\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Connectivity Analysis\n",
    "\n",
    "Analyze graph connectivity.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from semantica.kg import ConnectivityAnalyzer\n",
    "\n",
    "connectivity_analyzer = ConnectivityAnalyzer()\n",
    "\n",
    "connectivity = connectivity_analyzer.analyze_connectivity(kg)\n",
    "\n",
    "print(f\"Connectivity analysis:\")\n",
    "print(f\"  Is connected: {connectivity.get('is_connected', False)}\")\n",
    "print(f\"  Components: {len(connectivity.get('components', []))}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "You've learned how to analyze knowledge graphs:\n",
    "\n",
    "- **GraphAnalyzer**: Comprehensive graph analysis and metrics\n",
    "- **CentralityCalculator**: Calculate centrality measures\n",
    "- **CommunityDetector**: Detect communities in graphs\n",
    "- **ConnectivityAnalyzer**: Analyze graph connectivity\n",
    "\n",
    "Next: Learn how to deduplicate entities in the Deduplication notebook.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}