[GSoC 2023] Modifying drivingdistance

NEWS

@@ -80,6 +80,25 @@ pgRouting 3.6.0 Release Notes
 
     * ``pgr_KSP`` (`One To One`) added ``start_vid`` and ``end_vid`` column.
 
+
+* [#2548](https://github.com/pgRouting/pgrouting/pull/2548) Standarize output and modifying signature
+  pgr_drivingdistance
+
+  * New proposed functions:
+    * ``pgr_drivingdistance`` (`Single vertex`)
+    * ``pgr_drivingdistance`` (`Multiple vertices`)
+
+  * Deprecated signatures:
+
+    * ``pgr_drivingdistance(text,anyarray,double precision,boolean,boolean)``
+    * ``pgr_drivingdistance(text,bigint,double precision,boolean,boolean)``
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_drivingdistance`` (`Single vertex`) added ``depth`` and ``start_vid`` column.
+    * ``pgr_drivindistance`` (`Multiple vertices`) added ``depth`` column.
+
+
 **C/C++ code enhancements**
 
 * [#2504](https://github.com/pgRouting/pgrouting/pull/2504) To C++ pg data get,

doc/driving_distance/pgr_drivingDistance.rst

@@ -21,6 +21,13 @@
    Boost Graph Inside
 
 .. rubric:: Availability
+
+* Version 3.6.0
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_drivingdistance`` (`Single vertex`_) added ``depth`` and ``start_vid`` column.
+    * ``pgr_drivingdistance`` (`Multiple vertices`_) added ``depth`` column.
 
 * Version 2.1.0:
 
@@ -49,7 +56,7 @@ Signatures
    | pgr_drivingDistance(`Edges SQL`_, **Root vids**, **distance**, [**options**])
    | **options:** [directed, equicost]
 
-   | RETURNS SET OF |result-dij-dd|
+   | RETURNS SET OF |result-bfs|
 
 .. index::
    single: drivingDistance(Single vertex)
@@ -62,11 +69,11 @@ Single Vertex
 
    | pgr_drivingDistance(`Edges SQL`_, **Root vid**,  **distance**, [``directed``])
 
-   | RETURNS SET OF |result-1-1|
+   | RETURNS SET OF |result-bfs|
 
 :Example: From vertex :math:`11` for a distance of :math:`3.0`
 
-.. literalinclude:: doc-pgr_drivingDistance.queries
+.. literalinclude:: pgr_drivingDistance.queries
    :start-after: --q5
    :end-before: --q6
 
@@ -82,12 +89,12 @@ Multiple Vertices
    | pgr_drivingDistance(`Edges SQL`_, **Root vids**, **distance**, [**options**])
    | **options:** [directed, equicost]
 
-   | RETURNS SET OF |result-dij-dd-m|
+   | RETURNS SET OF |result-bfs|
 
 :Example: From vertices :math:`\{11, 16\}` for a distance of :math:`3.0` with
           equi-cost on a directed graph
 
-.. literalinclude:: doc-pgr_drivingDistance.queries
+.. literalinclude:: pgr_drivingDistance.queries
    :start-after: --q6
    :end-before: --q10
 
@@ -142,51 +149,17 @@ Edges SQL
 Result Columns
 -------------------------------------------------------------------------------
 
-Returns SET OF ``(seq, from_v, node, edge, cost, agg_cost)``
-
-.. list-table::
-   :width: 81
-   :widths: auto
-   :header-rows: 1
-
-   * - Parameter
-     - Type
-     - Description
-   * - ``seq``
-     - ``BIGINT``
-     - Sequential value starting from :math:`1`.
-   * - ``[from_v]``
-     - ``BIGINT``
-     - Identifier of the root vertex.
-
-   * - ``node``
-     - ``BIGINT``
-     - Identifier of ``node`` within the limits from ``from_v``.
-   * - ``edge``
-     - ``BIGINT``
-     - Identifier of the ``edge`` used to arrive to ``node``.
-
-       - :math:`0` when ``node`` = ``from_v``.
-
-   * - ``cost``
-     - ``FLOAT``
-     - Cost to traverse ``edge``.
-   * - ``agg_cost``
-     - ``FLOAT``
-     - Aggregate cost from ``from_v`` to ``node``.
-
-Where:
-
-:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
-:ANY-NUMERIC: SMALLINT, INTEGER, BIGINT, REAL, FLOAT, NUMERIC
+.. include:: BFS-category.rst
+   :start-after: mst-bfs-dfs-dd-result-columns-start
+   :end-before: mst-bfs-dfs-dd-result-columns-end
 
 Additional Examples
 -------------------------------------------------------------------------------
 
 :Example: From vertices :math:`\{11, 16\}` for a distance of :math:`3.0` on an
           undirected graph
 
-.. literalinclude:: doc-pgr_drivingDistance.queries
+.. literalinclude:: pgr_drivingDistance.queries
    :start-after: --q10
    :end-before: --q15
 

doc/src/migration.rst

@@ -20,6 +20,9 @@ Results can be different because of the changes.
 
 Migrating functions:
 
+:doc:`pgr_drivingDistance` signatures have changed, with the addition of new columns
+in the new signatures.
+
 :doc:`pgr_KSP` signatures have been changed, with the addition of new columns start_vid & end_vid
 in the new signatures. one to many, many to one, many to many, and combinations overloads have been added.
 
@@ -51,6 +54,52 @@ Migration of functions that add new columns
 .. contents:: Contents
    :local:
 
+Migration of ``pgr_drivingdistance``
+-------------------------------------------------------------------------------
+
+Starting from `v3.6.0 <https://docs.pgrouting.org/3.6/en/migration.html>`__
+
+Signatures to be migrated:
+
+* ``pgr_drivingdistance`` (`Single vertex`)
+* ``pgr_drivingdistance`` (`Multiple vertices`)
+
+:Before Migration:
+
+* Output columns were |result-dij-dd-m|
+
+  * Depending on the vertices, the column ``start_vid`` might be missing and the depth column is not in any one of them:
+
+    * ``pgr_drivingdistance`` (`Single vertex`) does not have ``start_vid`` and ``depth``.
+    * ``pgr_drivingdistance`` (`Multiple vertices`) does not have ``depth``.
+
+:Migration:
+
+* Be aware of the existance of the additional columns.
+
+* In ``pgr_drivingdistance`` (`Single vertex`)
+
+  * ``start_vid`` contains the **start vid** parameter value.
+  * ``depth`` contains the **depth** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --drivingdistance1
+   :end-before: --drivingdistance2
+
+* In ``pgr_drivingdistance`` (`Multiple vertices`)
+
+  * ``depth`` contains the **depth** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --drivingdistance2
+   :end-before: --drivingdistance3
+
+* If needed filter out the added columns, for example:
+
+.. literalinclude:: migration.queries
+   :start-after: --drivingdistance3
+   :end-before: --drivingdistance4
+
 Migration of ``pgr_KSP``
 -------------------------------------------------------------------------------
 

doc/src/pgRouting-introduction.rst

@@ -66,7 +66,8 @@ This Release Contributors
 Individuals in this release (in alphabetical order)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Aniket Agarwal
+Aniket Agarwal,
+Aryan Gupta,
 Ashish Kumar,
 Cayetano Benavent,
 Daniel Kastl,
@@ -108,6 +109,7 @@ Akio Takubo,
 Andrea Nardelli,
 Anthony Tasca,
 Anton Patrushev,
+Aryan Gupta,
 Ashraf Hossain,
 Ashish Kumar,
 Cayetano Benavent,

doc/src/release_notes.rst

@@ -101,6 +101,25 @@ pgRouting 3.6.0 Release Notes
 
     * ``pgr_KSP`` (`One To One`) added ``start_vid`` and ``end_vid`` column.
 
+
+* [#2548](https://github.com/pgRouting/pgrouting/pull/2548) Standarize output and modifying signature
+  pgr_drivingdistance
+
+  * New proposed functions:
+    * ``pgr_drivingdistance`` (`Single vertex`)
+    * ``pgr_drivingdistance`` (`Multiple vertices`)
+
+  * Deprecated signatures:
+
+    * ``pgr_drivingdistance(text,anyarray,double precision,boolean,boolean)``
+    * ``pgr_drivingdistance(text,bigint,double precision,boolean,boolean)``
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_drivingdistance`` (`Single vertex`) added ``depth`` and ``start_vid`` column.
+    * ``pgr_drivindistance`` (`Multiple vertices`) added ``depth`` column.
+
+
 .. rubric:: C/C++ code enhancements
 
 * `#2504 <https://github.com/pgRouting/pgrouting/pull/2504>`__ To C++ pg data get,

docqueries/driving_distance/CMakeLists.txt

@@ -1,6 +1,6 @@
 # Do not use extensions
 SET(LOCAL_FILES
-    doc-pgr_drivingDistance
+    pgr_drivingDistance
     )
 
 foreach (f ${LOCAL_FILES})

docqueries/driving_distance/dijksraDD-issue729.result

@@ -11,27 +11,26 @@ UPDATE edges AS edge_table
 SET node_count=count.sum
 FROM
         (SELECT
-        from_v,
+        start_vid,
         sum(node) AS sum
         FROM
             pgr_drivingDistance(
             'SELECT id, source, target, ST_Length(geom) AS cost FROM edges',
             ARRAY(SELECT DISTINCT source FROM edges),
             1,
             false)
-    GROUP BY from_v) AS count
-    WHERE edges.source=count.from_v
+    GROUP BY start_vid) AS count
+    WHERE edge_table.source=count.start_vid
     ;
-ERROR:  invalid reference to FROM-clause entry for table "edges"
-LINE 14:     WHERE edges.source=count.from_v
-                   ^
-HINT:  Perhaps you meant to reference the table alias "edge_table".
+UPDATE 16
 ALTER TABLE edges
 DROP COLUMN IF EXISTS another_column,
 ADD COLUMN another_column INTEGER;
-ERROR:  current transaction is aborted, commands ignored until end of transaction block
+NOTICE:  column "another_column" of relation "edges" does not exist, skipping
+ALTER TABLE
 DROP TABLE IF EXISTS network;
-ERROR:  current transaction is aborted, commands ignored until end of transaction block
+NOTICE:  table "network" does not exist, skipping
+DROP TABLE
 CREATE TABLE network AS
 SELECT *
 from (
@@ -41,30 +40,34 @@ from (
     (3::int, 3::int, 4::int, 100::int),
     (4::int, 5::int, 6::int, 100::int)
 ) as t (id, source,target,cost);
-ERROR:  current transaction is aborted, commands ignored until end of transaction block
+SELECT 4
 ALTER TABLE network
 DROP COLUMN IF EXISTS node_count,
 ADD COLUMN node_count INTEGER;
-ERROR:  current transaction is aborted, commands ignored until end of transaction block
+NOTICE:  column "node_count" of relation "network" does not exist, skipping
+ALTER TABLE
 UPDATE network AS network
 SET node_count=count.sum
 FROM
 (SELECT
-    from_v,
+    start_vid,
     sum(node) AS sum
     FROM
     pgr_drivingDistance(
         'SELECT id, source, target, cost FROM network',
         ARRAY(SELECT DISTINCT source FROM network),
         1,
         false)
-    GROUP BY from_v) AS count
-WHERE network.source=count.from_v
+    GROUP BY start_vid) AS count
+WHERE network.source=count.start_vid
 ;
-ERROR:  current transaction is aborted, commands ignored until end of transaction block
+NOTICE:
+No return values were found
+UPDATE 0
 ALTER TABLE network
 DROP COLUMN IF EXISTS another_column,
 ADD COLUMN another_column INTEGER;
-ERROR:  current transaction is aborted, commands ignored until end of transaction block
+NOTICE:  column "another_column" of relation "network" does not exist, skipping
+ALTER TABLE
 ROLLBACK;
 ROLLBACK

docqueries/driving_distance/dijksraDD-issue729.test.sql

@@ -10,16 +10,16 @@ UPDATE edges AS edge_table
 SET node_count=count.sum
 FROM
         (SELECT
-        from_v,
+        start_vid,
         sum(node) AS sum
         FROM
             pgr_drivingDistance(
             'SELECT id, source, target, ST_Length(geom) AS cost FROM edges',
             ARRAY(SELECT DISTINCT source FROM edges),
             1,
             false)
-    GROUP BY from_v) AS count
-    WHERE edges.source=count.from_v
+    GROUP BY start_vid) AS count
+    WHERE edge_table.source=count.start_vid
     ;
 
 ALTER TABLE edges
@@ -46,16 +46,16 @@ UPDATE network AS network
 SET node_count=count.sum
 FROM
 (SELECT
-    from_v,
+    start_vid,
     sum(node) AS sum
     FROM
     pgr_drivingDistance(
         'SELECT id, source, target, cost FROM network',
         ARRAY(SELECT DISTINCT source FROM network),
         1,
         false)
-    GROUP BY from_v) AS count
-WHERE network.source=count.from_v
+    GROUP BY start_vid) AS count
+WHERE network.source=count.start_vid
 ;
 
 ALTER TABLE network