add: directed and density based modualrity

Author: BeaMarton13

doc/source/community_detection_guide/notebooks/modularity.ipynb

@@ -193,7 +193,29 @@
    "source": [
     "*Note:* Based on our previous analysis, the \"good\" partitioning yields a significantly higher modularity score. It is important to note, however, that a high modularity score is not always a definitive indicator of a better community partitioning, as was previously demonstrated with the Grid Graph [here](test_significance_of_community.ipynb).\n",
     "\n",
-    "### Why the Resolution Parameter is Important\n",
+    "# Directed Modularity\n",
+    "\n",
+    "While the classic modularity formula works for undirected networks, a different approach is needed for **directed networks**, where edges have a specific direction (e.g., from node *i* to node *j*). In this context, the direction of an edge is crucial and should not be ignored.\n",
+    "\n",
+    "The directed modularity formula is:\n",
+    "\n",
+    "$$Q_{dir} = \\frac{1}{m} \\sum_{i,j} \\left[ A_{ij} -  \\gamma \\frac{k_{i}^{out} k_{j}^{in}}{m} \\right] \\delta(c_i, c_j)$$\n",
+    "\n",
+    "Where:\n",
+    "* $m$: Total number of directed edges in the graph.\n",
+    "* $A_{ij}$: Element of the adjacency matrix, representing the weight of the edge from node $i$ to node $j$.\n",
+    "* $k_{i}^{out}$: The **out-degree** of node $i$ (the sum of weights of edges leaving node *i*).\n",
+    "* $k_{j}^{in}$: The **in-degree** of node $j$ (the sum of weights of edges entering node *j*).\n",
+    "* $\\gamma$ is the resolution parameter. The default value is 1.0.\n",
+    "* $\\delta(c_i, c_j)$: Kronecker delta function, which is 1 if node $i$ and node $j$ belong to the same community ($c_i = c_j$), and 0 otherwise.\n",
+    "\n",
+    "### Why does the direction of edges matter?\n",
+    "* **Flipping a single edge:** Reversing a single edge (e.g., from A → B to B → A) will change the modularity score. This is because the out-degree of A and the in-degree of B would change, altering the null model's calculation and, consequently, the overall score.\n",
+    "* **Flipping all edges:** If you reverse the direction of **every single edge** in the network, the modularity score will **remain the same**. This is due to a symmetry property of the formula. The set of in-degrees becomes the new set of out-degrees, and vice versa. When the formula is applied to this completely reversed network, the total modularity score is unchanged. This is a fascinating property of directed modularity.\n",
+    "\n",
+    "\n",
+    "\n",
+    "# Why the resolution parameter is important\n",
     "\n",
     "The resolution parameter addresses a fundamental limitation of the original modularity measure, known as the **\"resolution limit\"**. This is the tendency of the original formula (where $\\gamma=1$) to fail at detecting small communities, especially in large graphs. It often merges smaller, distinct communities into a single larger one to maximize the modularity score.\n",
     "\n",
@@ -202,7 +224,34 @@
     "* $\\gamma > 1$: Increasing the resolution parameter penalizes connections more heavily. This encourages the algorithm to find **fewer and larger communities**, as it becomes harder for smaller, highly connected groups to form their own separate communities.\n",
     "* $\\gamma < 1$: Decreasing the resolution parameter reduces the penalty. This allows the algorithm to find **more and smaller communities**, as it becomes easier for closely-knit groups to be identified as their own communities.\n",
     "\n",
-    "In essence, the resolution parameter provides a flexible way to explore the community structure of a network at different scales, moving beyond the limitations of a single, fixed-scale partition."
+    "In essence, the resolution parameter provides a flexible way to explore the community structure of a network at different scales, moving beyond the limitations of a single, fixed-scale partition.\n",
+    "# Density-based modularity for undirected graphs\n",
+    "\n",
+    "While modularity is a powerful metric, it suffers from a well-known flaw called the **resolution limit**. This problem causes the modularity-maximizing algorithm to fail to detect small, tightly-knit communities, especially in large networks. Instead of finding these small groups, it often merges them into a single larger one to maximize the modularity score.\n",
+    "\n",
+    "One alternative is to use a variant based on an **Erdős-Rényi null model**, sometimes called **density-based modularity**. Instead of comparing communities to a degree-preserving random graph (configuration model), it compares them to a uniform random graph with the same overall density.\n",
+    "\n",
+    "For a graph \\( G = (V, E) \\) with \\( n = |V| \\) nodes and \\( m = |E| \\) edges, the global **edge density** is\n",
+    "\n",
+    "$$p = \\frac{2m}{n(n-1)}$$\n",
+    "\n",
+    "\n",
+    "The **density-based modualrity** is defined as:\n",
+    "\n",
+    "\n",
+    "$$Q_{\\text{density}} = \\frac{1}{2m} \\sum_{i,j} \n",
+    "\\Big( A_{ij} - p \\Big) \\, \\delta(c_i, c_j),$$\n",
+    "\n",
+    "\n",
+    "where:\n",
+    "\n",
+    "* $n$: Total number of nodes in the graph.\n",
+    "* $m$: Total number of edges in the graph.\n",
+    "* $A_{ij}$: Element of the adjacency matrix, representing the weight of the edge from node $i$ to node $j$.\n",
+    "* $p$: expected probability of an edge.\n",
+    "* $\\delta(c_i, c_j)$: Kronecker delta function, which is 1 if node $i$ and node $j$ belong to the same community ($c_i = c_j$), and 0 otherwise.  \n",
+    "\n",
+    "In this formulation, the null model assumes **uniform edge probability**, so communities are favored if their **internal density** is higher than the global density.\n"
    ]
   }
  ],