Betweenness centrality new function (#2644)

* (betweennessCentrality) pgtap tests that need to pass

* (betweennessCentrality) sql functions

* (betweennessCentrality) C/C++ code

* (betweennessCentrality) adding documentation as experimental

* (betweennessCentrality) example for the documentation

* (betweennessCentrality) adding to the build

* (betweennessCentrality) adding to the list of signatures

* (NEWS) updating changes

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

configuration.conf

@@ -46,6 +46,7 @@ planar              | Y | Y | Y
 dominator           | Y | Y | Y
 ordering            | Y | Y | Y
 circuits            | Y | Y | Y
+metrics             | Y | Y | Y
 #----------------------
 # SQL only directories
 #----------------------

doc/metrics/CMakeLists.txt

@@ -0,0 +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

@@ -0,0 +1,148 @@
+..
+   ****************************************************************************
+    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/
+   ****************************************************************************
+
+|
+
+
+``pgr_betweennessCentrality``
+===============================================================================
+
+``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
+
+* Version 3.7.0
+
+  * New **experimental** function:
+
+    * ``pgr_betweennessCentrality``
+
+Description
+-------------------------------------------------------------------------------
+
+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
+-------------------------------------------------------------------------------
+
+.. rubric:: Summary
+
+.. admonition:: \ \
+   :class: signatures
+
+   pgr_betweennessCentrality(`Edges SQL`_, [``directed``])
+
+   | Returns set of ``(vid, centrality)``
+
+:Example: For a directed graph with edges :math:`\{1, 2, 3, 4\}`.
+
+.. literalinclude:: betweennessCentrality.queries
+   :start-after: -- q1
+   :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
+-------------------------------------------------------------------------------
+
+.. include:: allpairs-family.rst
+    :start-after: edges_start
+    :end-before: edges_end
+
+Optional parameters
+...............................................................................
+
+.. include:: dijkstra-family.rst
+    :start-after: dijkstra_optionals_start
+    :end-before: dijkstra_optionals_end
+
+Inner Queries
+-------------------------------------------------------------------------------
+
+Edges SQL
+...............................................................................
+
+.. include:: pgRouting-concepts.rst
+    :start-after: no_id_edges_sql_start
+    :end-before: no_id_edges_sql_end
+
+Result columns
+-------------------------------------------------------------------------------
+
+.. list-table::
+	:width: 81
+	:widths: auto
+	:header-rows: 1
+
+	* - Column
+	  - Type
+	  - Description
+	* - ``vid``
+	  - ``BIGINT``
+	  - Identifier of the vertex
+	* - ``centrality``
+	  - ``FLOAT``
+	  - Relative betweenness centrality score of the vertex (will be in range [0,1])
+
+See Also
+-------------------------------------------------------------------------------
+
+* Boost's `betweenness_centrality
+  <https://www.boost.org/doc/libs/1_84_0/libs/graph/doc/betweenness_centrality.html>`_
+* Queries use the :doc:`sampledata` network.
+
+.. rubric:: Indices and tables
+
+* :ref:`genindex`
+* :ref:`search`

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
 

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/CMakeLists.txt

@@ -0,0 +1,11 @@
+# Do not use extensions
+SET(LOCAL_FILES
+	betweennessCentrality
+    )
+
+foreach (f ${LOCAL_FILES})
+    configure_file("${f}.result" "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}.queries")
+    list(APPEND LOCAL_DOC_FILES  "${PGR_DOCUMENTATION_SOURCE_DIR}/${f}.queries")
+endforeach()
+
+set(PROJECT_DOC_FILES ${PROJECT_DOC_FILES} ${LOCAL_DOC_FILES} PARENT_SCOPE)

docqueries/metrics/betweennessCentrality.pg

@@ -0,0 +1,9 @@
+-- CopyRight(c) pgRouting developers
+-- Creative Commons Attribution-Share Alike 3.0 License : https://creativecommons.org/licenses/by-sa/3.0/
+
+/* -- q1 */
+SELECT * FROM pgr_betweennessCentrality(
+'SELECT id, source, target, cost, reverse_cost
+FROM edges where id < 5'
+) ORDER BY vid;
+/* -- q2 */

docqueries/metrics/betweennessCentrality.result

@@ -0,0 +1,21 @@
+BEGIN;
+BEGIN
+SET client_min_messages TO NOTICE;
+SET
+/* -- q1 */
+SELECT * FROM pgr_betweennessCentrality(
+'SELECT id, source, target, cost, reverse_cost
+FROM edges where id < 5'
+) ORDER BY vid;
+ vid | centrality
+-----+------------
+   5 |          0
+   6 |        0.5
+   7 |          0
+  10 |       0.25
+  15 |          0
+(5 rows)
+
+/* -- q2 */
+ROLLBACK;
+ROLLBACK

docqueries/metrics/test.conf

@@ -0,0 +1,12 @@
+#!/usr/bin/perl -w
+
+%main::tests = (
+    'any' => {
+        'files' => [qw(
+            betweennessCentrality.pg
+            )]
+    },
+
+);
+
+1;

include/drivers/metrics/betweennessCentrality_driver.h

@@ -0,0 +1,64 @@
+/*PGR-GNU*****************************************************************
+File: betweennessCentrality_driver.h
+
+Generated with Template by:
+Copyright (c) 2015 pgRouting developers
+Mail: project@pgrouting.org
+
+Function's developer:
+Copyright (c) 2024 Arun Thakur
+Mail: bedupako12mas at gmail.com
+
+------
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+ ********************************************************************PGR-GNU*/
+
+#ifndef INCLUDE_DRIVERS_METRICS_BETWEENNESSCENTRALITY_DRIVER_H_
+#define INCLUDE_DRIVERS_METRICS_BETWEENNESSCENTRALITY_DRIVER_H_
+#pragma once
+
+/* for size-t */
+#ifdef __cplusplus
+#   include <cstddef>
+using IID_t_rt = struct IID_t_rt;
+#else
+#   include <stddef.h>
+#include <stdbool.h>
+typedef struct IID_t_rt IID_t_rt;
+#endif
+
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void
+pgr_do_betweennessCentrality(
+    char*,
+    bool,
+
+    IID_t_rt**,
+    size_t*,
+    char**,
+    char**);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // INCLUDE_DRIVERS_METRICS_BETWEENNESSCENTRALITY_DRIVER_H_