Louvain Community Detection

What You’ll Learn

By the end of this lesson, you’ll be able to:

What Louvain Does

Louvain is a community detection algorithm.

It finds groups of nodes that are more densely connected to each other than to the rest of the network.

The Core Concept: Modularity

Louvain optimizes modularity--a measure of community quality.

Interpreting Modularity Scores

In general, scores above 0.4 typically indicate meaningful groupings worth investigating.

How Louvain Works

Louvain iteratively moves nodes between communities to maximize modularity.

A Metaphor: Party Guests

Imagine a party where guests naturally cluster into conversation groups.

Phase 1: Each person drifts toward the group where they know the most people.

Phase 2: Once groups stabilize, imagine each group as a single unit. These large group-units merge together based on whether more people would know each other in aggregate.

Result: A hierarchy of social clusters—​friend groups within larger social circles.

Hierarchical Communities

This two-phase process creates a hierarchy:

The Movies Dataset

Before applying Louvain to fraud, let’s practice on familiar data.

The Movies graph contains:

We’ll find communities of actors who frequently work together.

Run Louvain in Stats Mode

Run this query to preview what Louvain will find:

CALL gds.louvain.stats('actor-collaborations', {})

In this case, we’re not specifying YIELD or RETURN — this way we get to see the entire dataframe.

Interpreting Stats Results

You should get a table with similar results to this:

Key Configuration: maxLevels

The maxLevels parameter controls how many hierarchy levels Louvain runs.

The default is 10, but Louvain stops early if modularity stops improving.

Experiment with maxLevels

Compare results with different maxLevels:

CALL gds.louvain.stats('actor-collaborations', {
  maxLevels: 1
})
YIELD communityCount, modularity
RETURN 'maxLevels: 1' AS config, communityCount, modularity

CALL gds.louvain.stats('actor-collaborations', {
  maxLevels: 10
})
YIELD communityCount, modularity
RETURN 'maxLevels: 10' AS config, communityCount, modularity

Choosing maxLevels

Use fewer levels when:

Use more levels when:

Examine the results

The resulting table should look something like this:

Community consolidation

Your results should look something like this table:

Weighted Relationships

Louvain can use relationship weights to influence community assignment.

Let’s see this in action by running Louvain twice—​once unweighted, once weighted—​and comparing the results.

The wider network

Here they are in their wider network:

MATCH (source:Actor)-[r:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(target:Actor)
WHERE source.communityUnweighted = target.communityUnweighted
  AND source.communityWeighted <> target.communityWeighted
  AND source < target
WITH source, target, count(m) AS sharedMovies
ORDER BY sharedMovies ASC
LIMIT 1
MATCH path = (source)-[:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(target)
MATCH path2 = (source)-[]-()-[]-()
MATCH path3 = (target)-[]-()-[]-()
RETURN path, path2, path3

The wider network

Here they are in their wider network:

MATCH (source:Actor)-[r:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(target:Actor)
WHERE source.communityUnweighted <> target.communityUnweighted
  AND source.communityWeighted = target.communityWeighted
  AND source < target
WITH source, target, count(m) AS sharedMovies
ORDER BY sharedMovies DESC
LIMIT 1
MATCH path = (source)-[:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(target)
MATCH path2 = (source)-[]-()-[]-()
MATCH path3 = (target)-[]-()-[]-()
RETURN path, path2, path3

What This Demonstrates

Actors with few shared movies may be split apart when weights are applied. Actors with many shared movies may be pulled together despite structural separation.

For fraud detection, weighting by transaction amounts or frequency can help distinguish casual connections from meaningful relationships.

The tolerance parameter

Louvain stops when modularity improvements become negligible.

The tolerance parameter controls "negligible":

CALL gds.louvain.stats('actor-collaborations', {
  tolerance: 0.00001
})
YIELD communityCount, modularity
RETURN communityCount, modularity

Default (0.0001) works well for most cases.

High tolerance

Let’s see what happens if we up the tolerance to 1.0:

CALL gds.louvain.stats('actor-collaborations', {
  tolerance: 1.0
})
YIELD communityCount, modularity
RETURN communityCount, modularity

Lower tolerance

You can also lower the tolerance past 0.00001. In our case, the graph converges fairly quickly, so the difference is not huge.

However, let’s run it anyway and see what we get:

CALL gds.louvain.stats('actor-collaborations', {
  tolerance: 1e-9
})
YIELD communityCount, modularity
RETURN communityCount, modularity

Clean Up

Drop the projection:

CALL gds.graph.drop('actor-collaborations')

When Louvain Works Well

Louvain is ideal when:

Limitations

Louvain has some important limitations:

Resolution limit: May miss very small communities in large networks. If you need to find 3-person fraud cells in a million-node graph, Louvain might merge them into larger groups.

Non-deterministic: Results can vary slightly between runs due to node processing order. Community IDs will differ; community membership is usually stable.

Transfer: From Movies to Fraud

You’ve practiced Louvain on actor collaborations. Now let’s apply it: