---
title: "leidenbase.Rmd"
author: "Brent Ewing"
date: "1/19/2022"
output: html_vignette
vignette: >
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{leidenbase}
%\VignetteEncoding{UTF-8}
---
```{r setup, echo=FALSE, results='hide', message=FALSE}
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](http://dx.doi.org/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
``` r
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,
```{r}
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
```{r}
str(res)
```
The membership vector consists of the community value for each node. For example,
```{r}
head(res[['membership']])
```
The nodes that belong to community 1 are
```{r}
which(res[['membership']]==1)
```
The first three communities are
```{r}
# 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
``` c++
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.