Louvain/Leiden/Label Propagation and Community Detection: Resolution, Stability, and Validation

Learning outcomes

1. AtlasMart problem: merchandising segments appear in the graph, but are they stable?

AtlasMart wants product “communities” for catalog navigation. A dense group of products may be useful, but community detection does not discover an objective business taxonomy. Louvain and Leiden optimize modularity-style structure; Label Propagation spreads neighbor labels until a stable labeling or iteration limit. Their outputs depend on graph scope, orientation, weights, parameters, and sometimes randomness.

The safe question is not “what are the true communities?” It is “does this projection contain stable, interpretable structural groups that improve a measured decision?”

2. Community identifiers are opaque partition labels

3. Create two dense product groups with one weak bridge

// Remove only this lesson's synthetic nodes if rerunning after Lesson 1 cleanup.
MATCH (n:Product) WHERE n.productId STARTS WITH 'CH24-COM-' DETACH DELETE n;

UNWIND range(1,8) AS i
CREATE (:Product:CH24CommunityProduct {
  productId:'CH24-COM-' + toString(i),
  name:'Community Product ' + toString(i),
  chapter24:true
});

MATCH (p1:Product {productId:'CH24-COM-1'}), (p2:Product {productId:'CH24-COM-2'}),
      (p3:Product {productId:'CH24-COM-3'}), (p4:Product {productId:'CH24-COM-4'}),
      (p5:Product {productId:'CH24-COM-5'}), (p6:Product {productId:'CH24-COM-6'}),
      (p7:Product {productId:'CH24-COM-7'}), (p8:Product {productId:'CH24-COM-8'})
CREATE (p1)-[:RELATED_TO {strength:5.0}]->(p2),
       (p2)-[:RELATED_TO {strength:5.0}]->(p3),
       (p3)-[:RELATED_TO {strength:5.0}]->(p4),
       (p4)-[:RELATED_TO {strength:5.0}]->(p1),
       (p1)-[:RELATED_TO {strength:4.0}]->(p3),
       (p5)-[:RELATED_TO {strength:5.0}]->(p6),
       (p6)-[:RELATED_TO {strength:5.0}]->(p7),
       (p7)-[:RELATED_TO {strength:5.0}]->(p8),
       (p8)-[:RELATED_TO {strength:5.0}]->(p5),
       (p5)-[:RELATED_TO {strength:4.0}]->(p7),
       (p4)-[:RELATED_TO {strength:0.5}]->(p5);

CALL gds.graph.project(
  'atlas-ch24-community',
  'CH24CommunityProduct',
  {RELATED_TO:{orientation:'UNDIRECTED', properties:['strength']}}
)
YIELD graphName, nodeCount, relationshipCount
RETURN graphName, nodeCount, relationshipCount;

4. Run Louvain, Leiden, and Label Propagation as competing hypotheses

CALL gds.louvain.stats('atlas-ch24-community', {
  relationshipWeightProperty:'strength',
  maxLevels:10,
  maxIterations:10,
  tolerance:0.0001,
  concurrency:2
}) YIELD communityCount, modularity, ranLevels, communityDistribution
RETURN *;

CALL gds.louvain.stream('atlas-ch24-community', {
  relationshipWeightProperty:'strength', concurrency:2
}) YIELD nodeId, communityId
RETURN gds.util.asNode(nodeId).productId AS productId, communityId
ORDER BY communityId, productId;

CALL gds.leiden.stream('atlas-ch24-community', {
  relationshipWeightProperty:'strength',
  gamma:1.0,
  theta:0.01,
  randomSeed:24,
  concurrency:2
}) YIELD nodeId, communityId
RETURN gds.util.asNode(nodeId).productId AS productId, communityId
ORDER BY communityId, productId;

CALL gds.labelPropagation.stream('atlas-ch24-community', {
  relationshipWeightProperty:'strength',
  maxIterations:10,
  concurrency:2
}) YIELD nodeId, communityId
RETURN gds.util.asNode(nodeId).productId AS productId, communityId
ORDER BY communityId, productId;

The fixture is designed with two dense four-node blocks and one weak bridge, so “two groups” is a reasonable structural hypothesis to check. Do not hard-code numeric community IDs in an acceptance test; IDs are labels, not stable domain keys.

5. Resolution and randomness need explicit experiments

UNWIND [0.5, 1.0, 2.0] AS gamma
CALL gds.leiden.stats('atlas-ch24-community', {
  relationshipWeightProperty:'strength',
  gamma:gamma,
  theta:0.01,
  randomSeed:24,
  concurrency:2
})
YIELD communityCount, modularity
RETURN gamma, communityCount, modularity
ORDER BY gamma;

UNWIND [11,24,37] AS seed
CALL gds.leiden.stats('atlas-ch24-community', {
  relationshipWeightProperty:'strength',
  gamma:1.0,
  randomSeed:seed,
  concurrency:2
})
YIELD communityCount, modularity
RETURN seed, communityCount, modularity
ORDER BY seed;

Do not assume higher modularity or more communities is automatically a better product taxonomy. Record whether the partition is stable enough for the intended downstream use and compare it with human judgments or a known fixture.

6. Compare partitions without comparing raw IDs

A simple hand-checkable stability measure is pair agreement: for every pair of products, ask whether each run puts the pair in the same community. Compare that Boolean relation across runs. This avoids pretending that community ID 17 from one run must equal community ID 17 from another.

from itertools import combinations

def pair_signature(assignments):
    # assignments: {product_id: opaque_community_id}
    return {
        tuple(sorted((a, b))): assignments[a] == assignments[b]
        for a, b in combinations(assignments, 2)
    }

def agreement(a, b):
    sa, sb = pair_signature(a), pair_signature(b)
    keys = sa.keys() & sb.keys()
    return sum(sa[k] == sb[k] for k in keys) / len(keys)

# Feed this with actual streamed assignments from two runs.
# Do not paste invented community IDs into the course evidence.

7. Deliberately wrong: rename community IDs as “customer segments”

A common failure is to persist communityId, display “Segment 42,” and let business workflows depend on it. A refreshed graph may split or merge groups; a parameter change may relabel IDs; a different algorithm may optimize another objective.

Repair by treating the partition as a versioned analytical artifact: store algorithm, projection fingerprint, parameter set, source-data cutoff, evaluation metrics, and a separate governed business-segment key only after validation. If the product needs stable segmentation, stability itself is a requirement to measure.

Production judgment and bridge

Next, AtlasMart shifts from grouping a whole graph to generating pairwise candidates: “which customers or products are similar?” That exposes the difference between structural Node Similarity and property-based KNN.

Summary and next step

Louvain/Leiden/Label Propagation and Community Detection: Resolution, Stability, and Validation is useful only when its assumptions and observed evidence stay attached to the decision. The examples above establish a reproducible mechanism and boundary; they do not turn one lab result into a universal production rule.

Next, continue to Node Similarity, KNN, Jaccard/Overlap/Cosine Concepts, and Candidate Generation. Carry forward the verified assumptions, fixture state, version/edition boundaries, and measurements from this lesson instead of treating the next topic as an isolated recipe.

Authoritative references

• GDS Manual v2026.07 — Current Graph Data Science manual and release baseline.
• GDS supported Neo4j versions — Compatibility matrix mapping Neo4j 2026.07 to GDS 2026.07.
• GDS editions — Community includes all algorithms but caps concurrency at four CPU cores and the model catalog at three models; Enterprise adds operational capabilities.
• Algorithm syntax and execution modes — stream/stats/mutate/write/estimate semantics and common algorithm configuration.
• Memory estimation — Estimate memory before allocating algorithm working state.
• Centrality algorithms — Current centrality family and quality tiers.
• Degree Centrality — Degree semantics and weighted/directed behavior.
• PageRank — PageRank iteration, damping, weights, and execution modes.
• Betweenness Centrality — Exact/sampled betweenness, samplingSize/samplingSeed, memory and concurrency tradeoffs.
• Eigenvector Centrality — Transitive influence and power-iteration semantics.
• Louvain — Modularity, levels, tolerance, seeding and execution modes.
• Leiden — Community detection with gamma, theta, randomSeed and connectivity refinement.
• Label Propagation — Fast topology-driven community detection, optional weights and seeds.
• Node Similarity — Structural neighborhood similarity with Jaccard, Overlap, or Cosine.
• K-Nearest Neighbors — Property-based approximate KNN and supported metrics.
• Path finding algorithms — Current shortest path, traversal, spanning, and flow families.
• Dijkstra Source-Target — Positive-cost shortest path semantics; sourceNode/targetNodes current syntax.
• Breadth First Search — Reachability traversal, targets, maxDepth, and stream/mutate modes.
• Graph algorithm operations reference — Current procedure/function names including spanningTree and similarity functions.
• Neo4j current versions — Current Neo4j database release and 5.26 LTS line.