GSoC 2024: Betweenness Centrality: Week 12

.github/workflows/boost_version.yml

@@ -27,6 +27,7 @@ name: Boost supported versions
 # - 1.56 is the minimum version we ask (Aug 2014)
 
 on:
+  workflow_dispatch:
   push:
     paths:
       - '.github/workflows/boost_version.yml'

.github/workflows/check-queries.yml

@@ -12,6 +12,7 @@ name: Check queries
 # - the latest postgis version
 
 on:
+  workflow_dispatch:
   push:
     paths:
       - '.github/workflows/check-queries.yml'

.github/workflows/clang.yml

@@ -11,6 +11,7 @@ name: Build for Ubuntu with clang
 # - postgis 3
 
 on:
+  workflow_dispatch:
   push:
     paths:
       - '.github/workflows/clang.yml'

.github/workflows/tidy-check.yml

@@ -1,6 +1,7 @@
 name: clang-tidy check
 
 on:
+  workflow_dispatch:
   pull_request:
     branches-ignore:
       - 'gh-pages'

NEWS.md

@@ -12,6 +12,12 @@ To see all issues & pull requests closed by this release see the [Git closed
 milestone for 3.7.0
 ](https://github.com/pgRouting/pgrouting/issues?utf8=%E2%9C%93&q=milestone%3A%22Release%203.7.0%22)
 
+**New experimental functions**
+
+* Metrics
+
+  * pgr_betweennessCentrality
+
 **Official functions changes**
 
 * [#2605](https://github.com/pgRouting/pgrouting/pull/2605) Standarize

doc/metrics/CMakeLists.txt

@@ -1,12 +1,12 @@
 
 SET(LOCAL_FILES
+    metrics-family.rst
     pgr_betweennessCentrality.rst
-    )
+   )
 
 foreach (f ${LOCAL_FILES})
     configure_file(${f} "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}")
     list(APPEND LOCAL_DOC_FILES  ${PGR_DOCUMENTATION_SOURCE_DIR}/${f})
 endforeach()
 
 set(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)
-

doc/metrics/metrics-family.rst

@@ -0,0 +1,41 @@
+..
+   ****************************************************************************
+    pgRouting Manual
+    Copyright(c) pgRouting Contributors
+
+    This documentation is licensed under a Creative Commons Attribution-Share
+    Alike 3.0 License: https://creativecommons.org/licenses/by-sa/3.0/
+   ****************************************************************************
+
+|
+
+
+
+Metrics - Family of functions
+===============================================================================
+
+.. rubric:: Experimental
+
+.. include:: experimental.rst
+   :start-after: begin-warn-expr
+   :end-before: end-warn-expr
+
+.. index experimental from here
+
+* :doc:`pgr_betweennessCentrality` - Calculates relative betweenness centrality using Brandes Algorithm
+
+.. index experimental to here
+
+
+.. toctree::
+    :hidden:
+
+    pgr_betweennessCentrality
+
+See Also
+-------------------------------------------------------------------------------
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

doc/metrics/pgr_betweennessCentrality.rst

@@ -13,23 +13,42 @@
 ``pgr_betweennessCentrality``
 ===============================================================================
 
-``pgr_betweennessCentrality`` - Returns the relative betweeness centrality of 
-all vertices in a graph using Brandes Algorithm.
+``pgr_betweennessCentrality`` - Calculates the relative betweeness centrality
+using Brandes Algorithm
 
 .. figure:: images/boost-inside.jpeg
    :target: https://www.boost.org/doc/libs/1_84_0/libs/graph/doc/betweenness_centrality.html
 
    Boost Graph Inside
 
 .. rubric:: Availability
-.. TODO: Add availability
+
+* Version 3.7.0
+
+  * New **experimental** function:
+
+    * ``pgr_betweennessCentrality``
 
 Description
 -------------------------------------------------------------------------------
 
-The Brandes Algorithm for utilises the sparse nature of graphs to evaluating the
-betweenness centrality score of all edges/vertices.
-We use Boost's implementation which runs in :math:`\Theta(VE)` time and uses :math:`\Theta(VE)` space.
+The Brandes Algorithm takes advantage of the sparse graphs for evaluating the
+betweenness centrality score of all vertices.
+
+
+Betweenness centrality measures the extent to which a vertex lies on the
+shortest paths between all other pairs of vertices. Vertices with a high
+betweenness centrality score may have considerable influence in a network by the
+virtue of their control over the shortest paths passing between them.
+
+The removal of these vertices will affect the network by disrupting the
+it, as most of the shortest paths between vertices pass through them.
+
+This implementation work for both directed and undirected graphs.
+
+- Running time:  :math:`\Theta(VE)`
+- Running space: :math:`\Theta(VE)`
+- Throws when there are no edges in the graph
 
 Signatures
 -------------------------------------------------------------------------------
@@ -41,16 +60,38 @@ Signatures
 
    pgr_betweennessCentrality(`Edges SQL`_, [``directed``])
 
-   | Returns set of ```(seq, vid, centrality)``` 
-   | OR EMPTY SET
+   | Returns set of ``(vid, centrality)``
 
-.. TODO: Fix this when docqueries are made 
-
-:Example: For a directed subgraph with edges :math:`\{1, 2, 3, 4\}`.
+:Example: For a directed graph with edges :math:`\{1, 2, 3, 4\}`.
 
 .. literalinclude:: betweennessCentrality.queries
    :start-after: -- q1
-   :end-before: Implicit Cases (directed)
+   :end-before: -- q2
+
+.. rubric:: Explanation
+
+* The betweenness centrality are between parenthesis.
+* The leaf vertices have betweenness centrality :math:`0`.
+* Betweenness centrality of vertex :math:`6` is higher than of vertex :math:`10`.
+
+  * Removing vertex :math:`6` will create three graph components.
+  * Removing vertex :math:`10` will create two graph components.
+
+.. graphviz::
+
+    digraph G {
+        5, 7, 15 [shape=circle;style=filled;width=.5;color=deepskyblue;fontsize=8;fixedsize=true;];
+        6, 10 [shape=circle;style=filled;width=.5;color=green;fontsize=8;fixedsize=true;];
+        5 [pos="0,0!";label="5 (0)"];
+        6 [pos="0,1!"label="6 (0.5)"];
+        7 [pos="0,2!"label="7 (0)"];
+        10 [pos="1,1!"label="10 (0.25)"];
+        15 [pos="2,1!"label="15 (0)"];
+        5 -> 6 [dir=both;label="1  "];
+        6->7 [dir=both;label="4  "];
+        10->6 [label="3"];
+        15->10 [label="4"];
+    }
 
 Parameters
 -------------------------------------------------------------------------------
@@ -83,26 +124,23 @@ Result columns
 	:width: 81
 	:widths: auto
 	:header-rows: 1
-	
+
 	* - Column
 	  - Type
 	  - Description
-	* - ``seq``
-	  - ``INTEGER``
-	  - Sequential Value starting from ``1``
 	* - ``vid``
 	  - ``BIGINT``
 	  - Identifier of the vertex
 	* - ``centrality``
-	  - ``FLOAT``	
-	  - relative betweenness centrality score of the vertex (will be in range [0,1])
+	  - ``FLOAT``
+	  - Relative betweenness centrality score of the vertex (will be in range [0,1])
 
 See Also
 -------------------------------------------------------------------------------
 
-* Boost `centrality
+* Boost's `betweenness_centrality
   <https://www.boost.org/doc/libs/1_84_0/libs/graph/doc/betweenness_centrality.html>`_
-* Queries uses the :doc:`sampledata` network.
+* Queries use the :doc:`sampledata` network.
 
 .. rubric:: Indices and tables
 

doc/src/experimental.rst

@@ -83,6 +83,12 @@ Experimental Functions
    :start-after: index from here
    :end-before: index to here
 
+:doc:`metrics-family`
+
+.. include:: metrics-family.rst
+   :start-after: index experimental from here
+   :end-before: index experimental to here
+
 :doc:`TRSP-family`
 
 .. include:: TRSP-family.rst
@@ -96,6 +102,7 @@ Experimental Functions
    transformation-family
    components-family
    ordering-family
+   metrics-family
 
 .. rubric:: categories
 
@@ -121,7 +128,6 @@ Experimental Functions
 - :doc:`pgr_transitiveClosure`
 - :doc:`pgr_lengauerTarjanDominatorTree`
 - :doc:`pgr_hawickCircuits`
-- :doc:`pgr_betweennessCentrality`
 
 .. toctree::
   :hidden:
@@ -137,7 +143,6 @@ Experimental Functions
   pgr_transitiveClosure
   pgr_lengauerTarjanDominatorTree
   pgr_hawickCircuits
-  pgr_betweennessCentrality
 
 
 See Also

doc/src/release_notes.rst

@@ -43,6 +43,12 @@ To see all issues & pull requests closed by this release see the `Git closed
 milestone for 3.7.0
 <https://github.com/pgRouting/pgrouting/issues?utf8=%E2%9C%93&q=milestone%3A%22Release%203.7.0%22>`__
 
+.. rubric:: New experimental functions
+
+* Metrics
+
+  * pgr_betweennessCentrality
+
 .. rubric:: Official functions changes
 
 * `#2605 <https://github.com/pgRouting/pgrouting/pull/2605>`__ Standarize

docqueries/metrics/betweennessCentrality.pg

@@ -6,65 +6,4 @@ SELECT * FROM pgr_betweennessCentrality(
 'SELECT id, source, target, cost, reverse_cost
 FROM edges where id < 5'
 ) ORDER BY vid;
-/* Implicit Cases (directed) */
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 2'
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 3'
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 4'
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 5'
-) ORDER BY vid;
-
-/* Explicit Cases (undirected) */
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 2', directed => false
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 3', directed => false
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 4', directed => false
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 5', directed => false
-) ORDER BY vid;
-
-/* Explicit Cases (directed) */
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 2', directed => true 
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 3', directed => true
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 4', directed => true
-) ORDER BY vid;
-
-SELECT * FROM pgr_betweennessCentrality(
-  'SELECT id, source, target, cost, reverse_cost
-  FROM edges where id < 5', directed => true
-) ORDER BY vid;
+/* -- q2 */