Yog.Community.Leiden (YogEx v0.97.0)

Leiden algorithm for community detection.

An improvement over the Louvain algorithm that guarantees well-connected communities. Adds a refinement step to ensure communities are properly connected internally.

Algorithm

The Leiden method works in three phases that repeat until convergence:

Local Optimization (like Louvain): Nodes move to improve modularity
Refinement: Partition communities into well-connected sub-communities
Aggregation: Communities become super-nodes
Repeat until convergence

Key Differences from Louvain

Feature	Louvain	Leiden
Speed	Faster	Slightly slower
Well-connected communities	Not guaranteed	✓ Guaranteed
Hierarchical quality	Good	Better
Disconnected communities	Possible	Prevented

When to Use

When community quality matters more than raw speed
When you need meaningful multi-level structure
When disconnected communities would be problematic
For hierarchical analysis requiring well-connected communities at each level

Complexity

Time: Slightly slower than Louvain (refinement adds overhead)
Space: O(V + E) same as Louvain

Example

# Basic usage
communities = Yog.Community.Leiden.detect(graph)
IO.inspect(communities.num_communities)

# With custom options
options = [
  min_modularity_gain: 0.0001,
  max_iterations: 100,
  refinement_iterations: 5,
  seed: 42
]
communities = Yog.Community.Leiden.detect_with_options(graph, options)

# Hierarchical detection
dendrogram = Yog.Community.Leiden.detect_hierarchical(graph)

References

Summary

Types

leiden_options()

Options for the Leiden algorithm

Functions

default_options()

Returns default options for Leiden algorithm.

detect(graph)

Detects communities using the Leiden algorithm with default options.

detect_hierarchical(graph)

Full hierarchical Leiden detection.

detect_hierarchical_with_options(graph, opts)

Full hierarchical Leiden detection with custom options.

detect_with_options(graph, opts)

Detects communities using the Leiden algorithm with custom options.

Types

leiden_options()

@type leiden_options() :: %{
  min_modularity_gain: float(),
  max_iterations: integer(),
  refinement_iterations: integer(),
  resolution: float(),
  seed: integer()
}

Options for the Leiden algorithm

Functions

default_options()

@spec default_options() :: leiden_options()

Returns default options for Leiden algorithm.

Defaults

min_modularity_gain: 0.000001 - Stop when gain < threshold
max_iterations: 100 - Max iterations per phase
refinement_iterations: 5 - Refinement step iterations
resolution: 1.0 - Resolution parameter (gamma)
seed: 42 - Random seed for tie-breaking

detect(graph)

@spec detect(Yog.graph()) :: Yog.Community.Result.t()

Detects communities using the Leiden algorithm with default options.

Example

communities = Yog.Community.Leiden.detect(graph)
IO.inspect(communities.num_communities)

detect_hierarchical(graph)

@spec detect_hierarchical(Yog.graph()) :: Yog.Community.Dendrogram.t()

Full hierarchical Leiden detection.

Returns a dendrogram with all hierarchical levels.

Example

dendrogram = Yog.Community.Leiden.detect_hierarchical(graph)
IO.inspect(length(dendrogram.levels))

detect_hierarchical_with_options(graph, opts)

@spec detect_hierarchical_with_options(Yog.graph(), keyword() | map()) ::
  Yog.Community.Dendrogram.t()

Full hierarchical Leiden detection with custom options.

Example

options = [max_iterations: 50, seed: 123]
dendrogram = Yog.Community.Leiden.detect_hierarchical_with_options(graph, options)

detect_with_options(graph, opts)

@spec detect_with_options(Yog.graph(), keyword() | map()) :: Yog.Community.Result.t()

Detects communities using the Leiden algorithm with custom options.

Options

:min_modularity_gain - Stop when gain < threshold (default: 0.000001)
:max_iterations - Max iterations per phase (default: 100)
:refinement_iterations - Refinement step iterations (default: 5)
:resolution - Resolution parameter (gamma) (default: 1.0)
:seed - Random seed for tie-breaking (default: 42)

Example

options = [min_modularity_gain: 0.0001, refinement_iterations: 10]
communities = Yog.Community.Leiden.detect_with_options(graph, options)