# How to Perform Graph Analytics in Semantica: Centrality and Community Detection

> Master graph analytics in Semantica with CentralityCalculator and CommunityDetector. Discover node importance, community structure, and link prediction with automatic NetworkX acceleration.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Semantica's `CentralityCalculator` and `CommunityDetector` classes provide built-in graph analytics for node importance and community structure, with automatic NetworkX acceleration and pure-Python fallbacks.**

The `semantica-agi/semantica` repository ships with dedicated engines for graph analytics that work out-of-the-box. Whether you need to rank nodes by influence or uncover hidden clusters, the framework handles adjacency conversion, progress tracking, and algorithm dispatch automatically. Both engines reside in the `semantica.kg` module and normalize diverse graph inputs into a standard format before running computations.

## Centrality Analysis with `CentralityCalculator`

The centrality engine lives in [`semantica/kg/centrality_calculator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/centrality_calculator.py) and exposes a single class, **`CentralityCalculator`**, that computes degree, betweenness, closeness, eigenvector, and PageRank scores.

### Supported Centrality Metrics

Each metric method returns a dictionary containing the raw score map, an ordered `"rankings"` list, and algorithm-specific metadata such as `"max_degree"` or `"total_nodes"`. The helper **`calculate_all_centrality`** invokes every individual metric in sequence and aggregates them into one comprehensive report.

### NetworkX Acceleration and Pure-Python Fallback

On initialization, the calculator attempts to import **NetworkX** and stores the result in `self.use_networkx`. When NetworkX is available, Semantica delegates to its high-performance implementations. If NetworkX is absent, the class falls back to pure-Python routines that run on an adjacency list built by the `_build_adjacency` helper. Every algorithm follows the same lifecycle: log the start via `get_logger()`, optionally wrap execution in a `ProgressTracker` session, normalize the raw scores, and return the result dictionary.

```python
from semantica.kg import CentralityCalculator

graph = {
    "entities": [{"id": "A"}, {"id": "B"}, {"id": "C"}],
    "relationships": [
        {"source": "A", "target": "B"},
        {"source": "B", "target": "C"},
        {"source": "C", "target": "A"},
    ],
}

calc = CentralityCalculator()
all_centrality = calc.calculate_all_centrality(graph)

print("Degree centrality:", all_centrality["degree"]["centrality"])
print("PageRank:", all_centrality["pagerank"]["centrality"])

```

## Community Detection with `CommunityDetector`

The second engine, defined in [`semantica/kg/community_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/community_detector.py), is **`CommunityDetector`**. It identifies tightly-connected clusters using multiple algorithms.

### Available Algorithms

The public entry point **`detect_communities`** acts as a dispatcher: you supply an `algorithm` name (or the `method` alias), and it routes to the correct concrete implementation. Supported methods include **Louvain**, **Leiden**, **overlapping k-clique**, and **label-propagation**. With NetworkX installed, the dispatcher forwards to native routines such as `greedy_modularity_communities` and `k_clique_communities`. Without NetworkX, the class falls back to lightweight heuristics in `_basic_community_detection` and `_basic_overlapping_detection`.

The returned dictionary includes:

- `"communities"`: list of member sets.
- `"node_assignments"`: mapping from node to community ID.
- `"modularity"`: quality score of the partition.
- `"algorithm"`: name of the method used.

Additional helpers such as **`calculate_community_metrics`** and **`analyze_community_structure`** expose intra-community edge counts, inter-community edge statistics, and other structural quality indicators.

### Chunked Processing for Large Graphs

For large graphs, label propagation supports chunked processing via the `chunk_size` parameter. When the node count exceeds the threshold, Semantica automatically processes the graph in chunks to keep memory usage bounded.

```python
from semantica.kg import CommunityDetector

detector = CommunityDetector()
result = detector.detect_communities(graph, algorithm="louvain")

print("Found", len(result["communities"]), "communities")
print("Modularity:", result["modularity"])
print("Node assignments:", result["node_assignments"])

```

```python
detector = CommunityDetector()
communities = detector.detect_communities(
    graph,
    algorithm="label_propagation",
    max_iterations=200,
    random_seed=42,
    chunk_size=5000,
)

print("Communities detected:", len(communities["communities"]))

```

## Shared Infrastructure for Graph Analytics

Both engines rely on common utilities in the `semantica.utils` package to normalize inputs and monitor long-running tasks.

### Adjacency Construction

The `_build_adjacency` method converts any supported graph representation—whether a dictionary with a `"relationships"` key, a custom object, or an existing NetworkX graph—into a simple `{node: [neighbors]}` map.

### Progress Tracking and Logging

The `get_progress_tracker()` singleton, defined in [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py), can be enabled or disabled globally. Heavy steps start a tracking session with `start_tracking` and end with `stop_tracking`. Separately, [`semantica/utils/logging.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/logging.py) supplies `get_logger()`, which returns a module-specific logger (`centrality_calculator` or `community_detector`) for consistent debug and info output.

## End-to-End Example: Combining Centrality and Community Data

Because both classes accept the same normalized graph format, you can pipe centrality scores into community contexts for richer downstream analytics. The following example extracts the top five highest-degree nodes and prints each node's assigned Louvain community:

```python
centrality = CentralityCalculator().calculate_degree_centrality(graph)
communities = CommunityDetector().detect_communities(graph, algorithm="louvain")

top_nodes = centrality["rankings"][:5]
for entry in top_nodes:
    node = entry["node"]
    score = entry["score"]
    comm_id = communities["node_assignments"].get(node, None)
    print(f"Node {node}: degree={score:.3f}, community={comm_id}")

```

## Summary

- **`CentralityCalculator`** in [`semantica/kg/centrality_calculator.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/centrality_calculator.py) computes degree, betweenness, closeness, eigenvector, and PageRank, with a single `calculate_all_centrality` call for bulk reports.
- **`CommunityDetector`** in [`semantica/kg/community_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/community_detector.py) supports Louvain, Leiden, k-clique, and label-propagation via the `detect_communities` dispatcher.
- Both engines auto-detect NetworkX for acceleration and fall back to pure-Python adjacency-list implementations.
- Shared utilities `_build_adjacency`, `get_progress_tracker()`, and `get_logger()` standardize input handling and observability across all graph analytics workflows.

## Frequently Asked Questions

### Does Semantica require NetworkX to run graph analytics?

No. Semantica attempts to import NetworkX at initialization, but every algorithm has a pure-Python fallback that operates on an internal adjacency list. You only need to `pip install networkx` if you want the faster accelerated path.

### What graph formats does Semantica accept?

The `_build_adjacency` helper normalizes dictionaries with `"relationships"` arrays, custom graph objects, or existing NetworkX graphs into a uniform `{node: [neighbors]}` structure. This means most common representations work without manual conversion.

### How do I monitor the progress of long-running centrality or community calculations?

Both engines integrate with the lightweight `ProgressTracker` singleton from [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py). Each heavy step automatically starts and stops tracking sessions, and you can enable or disable the tracker globally via `get_progress_tracker()`.

### Which community detection algorithm should I use for large graphs?

For large graphs, use **`label_propagation`** with the `chunk_size` parameter (for example, `chunk_size=5000`). This activates chunked processing that keeps memory usage bounded while still converging on community structure.