leidenbase.Rmd
In leidenbase: R and C/C++ Wrappers to Run the Leiden find_partition() Function

require(knitr)
opts_chunk$set(error=FALSE, message=FALSE, warning=FALSE)
library(leidenbase)
library(igraph)

Introduction

Leidenbase consists of R and C++ interfaces for the basic community detection functions of Vincent Traags's Leidenalg package. The Leidenalg algorithm is described in the article

Traag, V.A., Waltman. L., Van Eck, N.-J. (2018). From Louvain to Leiden: guaranteeing well-connected communities. Scientific reports, 9(1), 5233. 10.1038/s41598-019-41695-z

Detailed information describing use of the leiden algorithm is available at

https://leidenalg.readthedocs.io/en/latest/

leidenalg source code is available at

https://github.com/vtraag/leidenalg

R Interface

The R interface consists of the leiden_find_partition function

leiden_find_partition( igraph, partition_type = c("CPMVertexPartition", "ModularityVertexPartition", "RBConfigurationVertexPartition", "RBERVertexPartition", "SignificanceVertexPartition", "SurpriseVertexPartition"), initial_membership = NULL, edge_weights = NULL, node_sizes = NULL, seed = NULL, resolution_parameter = 0.1, num_iter = 2, verbose = FALSE )

Arguments:

  igraph: R igraph graph.

  partition_type: String partition type name. Default is CPMVertexParition.

  initial_membership: Numeric vector of initial membership assignments of nodes.
                      These are 1-based indices. Default is one community per
                      node.

  edge_weights: Numeric vector of edge weights. Default is 1.0 for all edges.

  node_sizes: Numeric vector of node sizes. Default is 1 for all nodes.

  seed: Numeric random number generator seed. The seed value must be
        either NULL for random seed values or greater than 0 for a
        fixed seed value. Default is NULL.

  resolution_parameter: Numeric resolution parameter. The value must be
                        greater than 0.0. Default is 0.1. The
                        resolution_parameter is ignored
                        for the partition_types ModularityVertexPartition,   
                        SignificanceVertexPartition, and
                        SurpriseVertexPartition.

  num_iter: Numeric number of iterations. Default is 2.

  verbose: A logic flag to determine whether or not we should print run
           diagnostics.

Value:
   A named list consisting of a numeric vector where each value is the community
   to which the node belongs (1-based indices), a numeric quality value, a
   numeric modularity, a numeric significance, a numeric vector of edge weights
   within each community, a numeric vector of edge weights from each community,
   a numeric vector of edge weights to each community, and total edge weight.

In order to use leiden_find_partition, create or load an igraph graph and then call leiden_find_partition. For example,

library(igraph)
fpath <- system.file('testdata', 'igraph_n1500_edgelist.txt.gz', package='leidenbase')
zfp <- gzfile(fpath)
igraph <- read_graph(file = zfp, format='edgelist')
res <- leiden_find_partition(igraph, partition_type = 'CPMVertexPartition', seed = 123456, resolution_parameter = 0.5)

leiden_find_partition returns

str(res)

The membership vector consists of the community value for each node. For example,

head(res[['membership']])

The nodes that belong to community 1 are

which(res[['membership']]==1)

The first three communities are

# lim1 <- max(res$membership)
lim1 <- 3
for( i in seq(lim1)) {
  cat(paste0('Community ', i, ':'))
  for(j in which(res[['membership']]==i))
    cat(' ', j)
  cat('\n')
}

C/C++ Interface

The C/C++ interface consists of the leidenFindPartition function

int leidenFindPartition( igraph_t *pigraph,
                           std::string const partitionType,
                           std::vector < size_t > const *pinitialMembership,
                           std::vector < double > const *pedgeWeights,
                           std::vector < size_t > const *pnodeSizes,
                           size_t seed,
                           double resolutionParameter,
                           std::int32_t numIter,
                           std::vector < size_t > *pmembership,
                           std::vector < double > *pweightInCommunity,
                           std::vector < double > *pweightFromCommunity,
                           std::vector < double > *pweightToCommunity,
                           double *pweightTotal,
                           double *pquality,
                           double *pmodularity,
                           double *psignificance,
                           int *pstatus )

Parameters:

  igraph: pointer to igraph_t graph
  partitionType         partition type used for optimization
  initialMembership     vector of initial membership assignments of nodes (NULL
                        for default of one community per node)
  edgeWeights           vector of weights of edges (NULL for default of 1.0)
  nodeSizes             vector of node sizes (NULL for default of 1)
  seed                  random number generator seed (0=random seed)
  resolutionParameter   resolution parameter
  numIter               number of iterations
  pmembership           vector of node membership assignments
  pweightInCommunity    vector of edge weights within community
  pweightFromCommunity  vector of edge weights from community
  pweightToCommunity    vector of edge weights to community
  pweightTotal          total edge weights
  pquality              partition quality
  pmodularity           partition modularity
  psignificance         partition significance
  pstatus               function status (0=success; -1=failure)

Notes for the C/C++ interface:

Edit leidenFindPartition.cpp to set the preprocessor definition R_INTERFACE to 0.
The resolution parameter is ignored for the partition types ModularityVertexPartition, SignificanceVertexPartition, and SurpriseVertexPartition
To use the leidenFindPartition function, compile and link to the files src/leidenFindPartition.(cpp|h), src/leidenalg/src/*.cpp, and src/leidenalg/include/*.h and a C igraph object library.