Louvain Method

Introduction

The Louvain method algorithm is a hierarchical clustering method used to discover community structures in networks. It detects groups of nodes that exhibit strong internal connections while maintaining sparse connections with nodes in other groups. This is accomplished by optimizing a modularity score, which evaluates the quality of network partitions into distinct communities.

For a variant that adds a refinement phase and guarantees that every community it reports is internally connected, see the Leiden algorithm.

Output

The algorithm produces the following fields:

Field Name	Description
id	The ID of the node (vertex)
communityId	A generated integer ID representing the community of the node (vertex)
intermediateCommunityIds	Community identifiers for the node at each hierarchy level

Query Example

cyphergremlin

CALL algo.louvain({
    labels: ['User'],
    relationshipTypes: ['LINK'],
    maxIterations: 30,
    relationshipWeightProperty: 'weight',
    maxLevels: 1,
    threshold: 0.0001,
    largeCommunityThreshold: 100000,
    seed: 42
    }) YIELD id, communityId
RETURN id, communityId

graph.program(
  LouvainProgram.build()
    .vertices("User")
    .edges("LINK")
    .maxIteration(30)
    .maxLevels(1)
    .setParams("weight", "weight", "threshold", 0.0001, "largeCommunityThreshold", 100000, "seed", 42)
    .create()
).submitAndGet().toList()

Parameters

cyphergremlin

Name	Description	Required	Default Value
labels	Specifies the node labels to include in the algorithm	Yes
relationshipTypes	Specifies the relationship types to include	Yes
maxIterations	Maximum number of iterations	No	30
relationshipWeightProperty	Defines the property name for edge weights	No
maxLevels	Maximum hierarchy depth for community detection	No	1
threshold	Minimum modularity change required between iterations	No	0.0001
largeCommunityThreshold	Node count at or below which a hierarchy level is processed in memory	No	100000
seed	Random number generator seed for reproducible results	No

Method	Description	Required	Default Value
vertices(String... names)	Specifies the node (vertex) labels to include	Yes
edges(String... names)	Specifies the edge labels to include	Yes
maxIteration(int n)	Sets the maximum iteration count	No	30
maxLevels(int n)	Maximum hierarchy depth for community detection	No	1
setParams(Object... args)	Adds additional parameters using alternating keys and values	No	see below

Additional parameter keys in setParams

Key	Description	Default Value
weight	Specifies the edge weight property or a constant value as weight	1.0
threshold	Minimum modularity change required between iterations	0.0001
largeCommunityThreshold	Node count at or below which a hierarchy level is processed in memory	100000
seed	Random number generator seed for reproducible results

Exporting Query Results

For large datasets, export the results to object storage. An administrator registers the export locations, and a query names one of them plus the directory to write under, as <location>:<directory>. See Exporting Query Results for registering a location and for the supported storage types and file formats.

cyphergremlin

EXPORT TO 'my_export_location:louvain_results'
CALL algo.louvain({
    labels: ['User'],
    relationshipTypes: ['LINK'],
    relationshipWeightProperty: 'weight',
    maxLevels: 2
    }) YIELD id, communityId
RETURN id, communityId

graph.program(
    LouvainProgram.build()
            .maxIteration(20)
            .vertices("User")
            .edges("LINK")
            .setParams("weight", "amount", "threshold", 0.001)
            .create()
).submitAndSave([
  "exportTo": "my_export_location:louvain_results"
])