Compute.louvain()#

relationalai.std.graphs
#Compute.louvain(
    node: Producer,
    max_levels: int = 1,
    max_sweeps: int = 20,
    level_tolerance: float = 0.01,
    sweep_tolerance: float = 0.0001,
    randomization_seed: int | None = None
) -> Expression

Assign a community label to node using the Louvain method. The Louvain algorithm is a hierarchical community detection technique that initially assigns each node to its own community. It iteratively merges nodes and communities to maximize modularity, a metric that evaluates the density of edges within communities relative to edges between them. The process continues until no further improvements in modularity can be made, or the maximum number of iterations is reached. Must be called in a rule or query context.

Supported Graph Types#

Graph TypeSupportedNotes
DirectedNoCurrently not supported.
UndirectedYes
WeightedYesOnly positive weights are supported.
UnweightedYes

Parameters#

NameTypeDescriptionRange
nodeProducerA node in the graph.Vertex set.
max_levelsintThe maximum number of levels at which to optimize. Default is 1.Positive integer.
max_sweepsintThe maximum number of iterations to run at each level. Default is 20.Non-negative integer.
level_tolerancefloatThe minimum change in modularity required to continue to the next level. Default is 0.01.Small positive number or zero.
sweep_tolerancefloatThe minimum change in modularity required to continue to the next sweep. Default is 0.0001.Small positive number or zero.
randomization_seedint or NoneThe seed for the algorithm’s random number generator. Default is None.None or non-negative integer.

Returns#

Returns an Expression object that produces the integer community label assigned to node by the Louvain algorithm.

Example#

Use .louvain() to assign community labels to nodes in a graph using the Louvain algorithm. You access the .louvain() method from a Graph object’s .compute attribute:

#import relationalai as rai
from relationalai.std import alias
from relationalai.std.graphs import Graph

# Create a model named "socialNetwork" with a Person type.
model = rai.Model("socialNetwork")
Person = model.Type("Person")

# Add some people to the model and connect them with a multi-valued `friends` property.
with model.rule():
    alice = Person.add(name="Alice")
    bob = Person.add(name="Bob")
    carol = Person.add(name="Carol")
    daniel = Person.add(name="Daniel")
    evelyn = Person.add(name="Evelyn")
    alice.friends.add(bob)
    carol.friends.add(daniel)

# Create an undirected graph with Person nodes and edges between friends.
graph = Graph(model, undirected=True)
graph.Node.extend(Person)
graph.Edge.extend(Person.friends)

# Find the community label for a single person using Louvain.
with model.query() as select:
    community = graph.compute.louvain(Person(name="Alice"))
    response = select(alias(community, "community_label"))

print(response.results)
# Output:
#    community_label
# 0                2

# Find the community label for each person using Louvain.
with model.query() as select:
    person = Person()
    community = graph.compute.louvain(person)
    response = select(person.name, alias(community, "community_label"))

print(response.results)

#      name  community_label
# 0   Alice                2
# 1     Bob                2
# 2   Carol                1
# 3  Daniel                1
# 4  Evelyn                3

In this example, .louvain() finds three communities in the graph: Alice and Bob are in one community, and Carol and Daniel are in another. Evelyn is an isolated node and has been assigned a unique community ID.

See Also#