From 4469316d14961086e3f68aef5b213027039a98ba Mon Sep 17 00:00:00 2001 From: Mark Bonicillo Date: Fri, 10 Nov 2023 12:54:11 -0800 Subject: [PATCH 1/2] Update modularity docs --- docs/source/modularity.rst | 50 +++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/docs/source/modularity.rst b/docs/source/modularity.rst index 8738ced1..d77f4446 100644 --- a/docs/source/modularity.rst +++ b/docs/source/modularity.rst @@ -16,7 +16,7 @@ given partition of the vertices in a hypergraph. In general, higher modularity i partitioning of the vertices into dense communities. Two functions to generate such hypergraph -partitions are provided: **Kumar's** algorithm, and the simple **Last-Step** refinement algorithm. +partitions are provided: **Kumar's** algorithm, and the simple **last-step** refinement algorithm. The submodule also provides a function to generate the **two-section graph** for a given hypergraph which can then be used to find vertex partitions via graph-based algorithms. @@ -33,32 +33,22 @@ Using the Tool -------------- -Precomputation -^^^^^^^^^^^^^^ - -In order to make the computation of hypergraph modularity more efficient, some quantities need to be pre-computed. -Given hypergraph H, calling:: - - HG = hmod.precompute_attributes(H) - -will pre-compute quantities such as node strength (weighted degree), d-weights (total weight for each edge cardinality) and binomial coefficients. - Modularity ^^^^^^^^^^ Given hypergraph HG and a partition A of its vertices, hypergraph modularity is a measure of the quality of this partition. Random partitions typically yield modularity near zero (it can be negative) while positive modularity is indicative of the presence of dense communities, or modules. There are several variations for the definition of hypergraph modularity, and the main difference lies in the -weight given to different edges. Modularity is computed via:: +weight given to different edges given their size $d$ and purity $c$. Modularity is computed via:: - q = hmod.modularity(HG, A, wdc=linear) + q = hmod.modularity(HG, A, wdc=hmod.linear) -In a graph, an edge only links 2 nodes, so given partition A, an edge is either within a community (which increases the modularity) -or between communities. +where the 'wdc' parameter points to a function that controls the weights (details below). -With hypergraphs, we consider edges of size *d=2* or more. Given some vertex partition A and some *d*-edge *e*, let *c* be the number of nodes -that belong to the most represented part in *e*; if *c > d/2*, we consider this edge to be within the part. -Hyper-parameters *0 <= w(d,c) <= 1* control the weight +In a graph, an edge only links 2 nodes, so given partition A, an edge is either within a community (which increases the modularity) +or between communities. With hypergraphs, we consider edges of size $d=2$ or more. Given some vertex partition A and some $d$-edge $e$, let $c$ be the number of nodes +that belong to the most represented part in $e$; if $c > d/2$, we consider this edge to be within the part. +Hyper-parameters $0 \le w(d,c) \le 1$ control the weight given to such edges. Three functions are supplied in this submodule, namely: **linear** @@ -66,22 +56,23 @@ given to such edges. Three functions are supplied in this submodule, namely: **majority** $w(d,c) = 1$ if $c > d/2$, else $0$. **strict** - $w(d,c) = 1$ if $c == d$, else $0$. + $w(d,c) = 1$ iff $c = d$, else $0$. -The 'linear' function is used by default. More details in [2]. +The 'linear' function is used by default. Other functions $w(d,c)$ can be supplied as long as $0 \le w(d,c) \le 1$ and $w(d,c)=0$ when $c \le d$. +More details can be found in [2]. Two-section graph ^^^^^^^^^^^^^^^^^ -There are several good partitioning algorithms for graphs such as the Louvain algorithm and ECG, a consensus clustering algorithm. +There are several good partitioning algorithms for graphs such as the Louvain algorithm, Leiden and ECG, a consensus clustering algorithm. One way to obtain a partition for hypergraph HG is to build its corresponding two-section graph G and run a graph clustering algorithm. -Code is provided to build such graph via:: +Code is provided to build such a graph via:: G = hmod.two_section(HG) -which returns an igraph.Graph object. +which returns an igraph.Graph object. + - Clustering Algorithms ^^^^^^^^^^^^^^^^^^^^^ @@ -92,8 +83,8 @@ from each part inside each edge. Given hypergraph HG, this is called as:: K = hmod.kumar(HG) The other supplied algorithm is a simple method to improve hypergraph modularity directely. Given some -initial partition of the vertices (for example via Louvain on the two-section graph), move vertices between parts in order -to improve hypergraph modularity. Given hypergraph HG and initial partition A, this is called as:: +initial partition of the vertices (for example via Louvain on the two-section graph), we move vertices between parts in order +to improve hypergraph modularity. Given hypergraph HG and an initial partition A, it is called as follows:: L = hmod.last_step(HG, A, wdc=linear) @@ -103,8 +94,11 @@ where the 'wdc' parameter is the same as in the modularity function. Other Features ^^^^^^^^^^^^^^ -We represent a vertex partition A as a list of sets, but another conveninent representation is via a dictionary. -We provide two utility functions to switch representation, namely `A = dict2part(D)` and `D = part2dict(A)`. +We represent a vertex partition A as a list of sets, but another useful representation is via a dictionary. +We provide two utility functions to switch representation, namely:: + + A = dict2part(D) + D = part2dict(A) References ^^^^^^^^^^ From 225f584fbcb10ec5fb2ba299b3adffd6c9e05183 Mon Sep 17 00:00:00 2001 From: Mark Bonicillo Date: Fri, 10 Nov 2023 12:55:00 -0800 Subject: [PATCH 2/2] =?UTF-8?q?bump:=20version=202.1.0=20=E2=86=92=202.1.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cz.toml | 2 +- docs/source/conf.py | 2 +- hypernetx/__init__.py | 2 +- setup.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.cz.toml b/.cz.toml index 84d5a197..81efa307 100644 --- a/.cz.toml +++ b/.cz.toml @@ -1,6 +1,6 @@ [tool.commitizen] name = "cz_conventional_commits" -version = "2.1.0" +version = "2.1.1" version_files = [ "setup.py", "docs/source/conf.py", diff --git a/docs/source/conf.py b/docs/source/conf.py index 64bd4ae0..1ac22011 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,7 +19,7 @@ import os -__version__ = "2.1.0" +__version__ = "2.1.1" # If extensions (or modules to document with autodoc) are in another directory, diff --git a/hypernetx/__init__.py b/hypernetx/__init__.py index 07720448..dc5ef619 100644 --- a/hypernetx/__init__.py +++ b/hypernetx/__init__.py @@ -11,4 +11,4 @@ from hypernetx.utils import * from hypernetx.utils.toys import * -__version__ = "2.1.0" +__version__ = "2.1.1" diff --git a/setup.py b/setup.py index 16133e5f..6465d89e 100644 --- a/setup.py +++ b/setup.py @@ -1,5 +1,5 @@ from setuptools import setup -__version__ = "2.1.0" +__version__ = "2.1.1" setup(version=__version__)