Network Analysis¶

PikoClaw builds a directed communication graph from email patterns and computes network metrics using NetworkX. This reveals the hidden structure of communication networks: who are the key connectors, who holds authority, and what natural communities exist.

Optional dependency

Network analysis requires networkx, numpy, and scipy. Install with:

pip install pikoclaw[graph]

Without these, PikoClaw works normally but skips network-analysis.md and graph metric enrichment in contacts.json.

How It Works¶

Build graph -- Every email creates a directed edge from sender to each recipient. Edge weights count the number of messages.
Compute metrics -- HITS, PageRank, degree centrality, and Louvain communities are computed on the full graph.
Generate output -- Results appear in network-analysis.md and enrich each node in contacts.json.

Non-email items (calendar events, tasks) are excluded from the graph.

Metrics¶

HITS Authority Score¶

What it means: People who receive email from many important senders.

Authorities are the people everyone reaches out to. In an organization, these tend to be subject-matter experts, decision-makers, or people in critical roles that many teams depend on.

HITS Hub Score¶

What it means: People who send email to many important recipients.

Hubs are the connectors -- people who bridge different groups and distribute information widely. They tend to be coordinators, project managers, or executives who communicate across organizational boundaries.

PageRank¶

What it means: Overall influence in the communication network.

PageRank measures influence by considering not just how many people email someone, but how influential those people are. A person emailed by two VPs ranks higher than someone emailed by two interns, even if both receive the same number of messages.

Louvain Communities¶

What it means: Natural clusters in the communication network.

The Louvain algorithm detects groups of people who communicate more frequently with each other than with the rest of the network. These often map to teams, projects, or social circles.

Degree Centrality¶

What it means: Raw connection count.

In-degree: How many unique people email this person
Out-degree: How many unique people this person emails
Total degree: Combined unique connections

Output: network-analysis.md¶

The generated page includes:

Graph Summary -- Total participants, communication links, network density, communities detected.

Top Authorities -- Ranked table of the top 10 authority nodes with scores and message counts.

Top Hubs -- Ranked table of the top 10 hub nodes with scores and message counts.

Influence (PageRank) -- Top 10 by PageRank with in-degree and out-degree.

Most Connected -- Top 10 by total degree with directional breakdown.

Communication Communities -- Each detected cluster listed with members (up to 15 shown per community).

Output: contacts.json enrichment¶

When graph analysis runs, each node in contacts.json is enriched with:

{
  "hub_score": 0.234,
  "authority_score": 0.189,
  "pagerank": 0.0312,
  "community": 0,
  "degree": 28,
  "in_degree": 12,
  "out_degree": 16
}

These fields enable downstream visualization and analysis tools to render the communication network with intelligence baked in.

Interpreting Results¶

Knowledge Transfer Scenario¶

When extracting a departing employee's mailbox:

High authority contacts are the people who depend on this person for answers. They may need the most support during the transition.
High hub contacts are the people this person depended on. They can help onboard the replacement.
Community membership reveals which teams and projects this person was embedded in.

Compliance Scenario¶

Isolated communities may indicate information silos or shadow IT.
Bridge nodes (high hub + high authority) are people through whom sensitive information flows. They represent key risk points.
Density indicates how interconnected the network is -- low density may indicate poor cross-team communication.