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.

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: 10000,
    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", 10000, "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	Community count threshold that triggers optimized in-memory processing	No	10000
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	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	Community count threshold that triggers optimized in-memory processing	10000
seed	Random number generator seed for reproducible results

Exporting Query Results

For large datasets, export the results to object storage:

cyphergremlin

EXPORT TO 's3://my_bucket/target_dir'
PROPERTIES {
  catalog: 'puppygraph_catalog_name'
}
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": "s3://my_bucket/target_dir",
  "catalog": "puppygraph_catalog_name"
])