help luvain

Title

Find communities in weighted graph

Syntax

luvain
<source node var> <target node var> <edge weight var>, [REsolution(0<=number<=1)] [Reset(YES|no)] [Draw(string)]

Description

luvain exploits the Python integration which, Stata introduced starting
with version 16 (man python) and wraps itself around the Python module
"python-louvain" to find
clusters in a weighted graph.

It assumes you have loaded your network's weighted edges in stata
in the form of three variables. So if you have string variables "snode" (the source node)
and "tnode" (the target node) and some numerical variable "weight" then you feed the
weighted edges by running:

. luvain snode tnode weight

The command creates a frame called "luvain" in which it saves two variables:
one called "node" holding the unique values of snode and tnode combined and one called
"cluster_1" indicating the cluster each node belongs to.

If you run the command again it wipes the frame "luvain" away and starts over
unless you say:

. luvain snode tnode weight, reset(no)

in which case it adds "cluster_2" to the frame "luvain". A third run of:

. luvain snode tnode weight, reset(no)

will add "cluster_3" etc.

You might give it a resolution (defaults to 1) which is a number between
zero and one. The variable "cluster_i" is labeled with the resolution that produced it.
This way one can experiment around.

You might also ask it to plot the clusters. It will save "luvain.pdf" in c(pwd)
and open it with the default OS application.

You need Python 3.7 (go with Anaconda) and, besides Stata 16 or more, you need to
have configured your Stata to use the right Python on your system. To install
"python-louvain" run the command:

pip install python-louvain at the command line.

Examples

The command luvain_gcd takes an integer argument n. It then creates all
unique, unordered pairs of distinct integers between 1 and n and weighs them by their gcd minus 1.
This way the weight expresses codivisibility of the pair. Those with gcd=1 are dropped. You can use
this weight graph to play around with luvain.

For example, create the gcd weighted graph of 1,...10:

1.luvain_gcd 10.

Now partition it with luvain:

2.luvain snode tnode weight,

append a second partition to it with resolution .7, plot it:

3.luvain snode tnode weight, resolution(.7) reset(no) draw(yes),

and check the results:

4. frame change luvain

5. list

6. frame change default

References

1. Blondel, V. D., Guillaume, J. L., Lambiotte, R., & Lefebvre, E. (2008).
Fast unfolding of communities in large networks. Journal of statistical mechanics: theory and experiment.

2. Newman, M. E. (2004). Analysis of weighted networks.

3. python-louvain module. Copyright (c) 2009-2018, Thomas Aynaud

Remarks

The main purpose of this module is to demonstrate that polyglotism is as useful in programming as in natural languages. It imports an implementation of an algorithm (Luvain) of a certain type of unsupervised learning (modularity based) to Stata and at the same time it demonstrates several new features in Stata. It uses the Stata Function Interface (sfi) which is an API developed by Stata to allow interaction of Stata with python. Writing it allowed me to practice using sfi and also to learn stata frames (man frames). It applies the following sfi classes: sfi.Data, sfi.Macro and sfi.Frame. I hope people will have fun disecting it.

Author

Nikos Askitas, IZA - Institute of Labor Economics, Bonn, Germany.

Email: nikos@iza.org, Twitter: @askitas

Web: askitas.com