Deprecate pgr_analyzeGraph

NEWS.md

@@ -8,25 +8,37 @@
 
 ### pgRouting 3.8.0 Release Notes
 
+To see all issues & pull requests closed by this release see the [Git closed
+milestone for 3.8.0
+](https://github.com/pgRouting/pgrouting/issues?utf8=%E2%9C%93&q=milestone%3A%22Release%203.8.0%22)
+
 **Promotion to official function of pgRouting.**
 
-* pgr_extractVertices
+* [#2772](https://github.com/pgRouting/pgrouting/issues/2772):
+  pgr_extractVertices
 
   * Error messages adjustment.
   * Function promoted to official.
 
-* pgr_degree
+* [#2760](https://github.com/pgRouting/pgrouting/issues/2760):
+  pgr_degree
 
   * Error messages adjustment.
   * New signature with only Edges SQL.
   * Function promoted to official.
 
-* pgr_findCloseEdges
+* [#2774](https://github.com/pgRouting/pgrouting/issues/2774):
+  pgr_findCloseEdges
 
   * Error messages adjustment.
   * ``partial`` option is removed.
   * Function promoted to official.
 
+**Deprecation of functions.**
+
+* [#2753](https://github.com/pgRouting/pgrouting/issues/2753):
+  pgr_analyzeGraph
+
 **Official functions changes**
 
 * [#2786](https://github.com/pgRouting/pgrouting/issues/2786): pgr_contraction

doc/metrics/pgr_degree.rst

@@ -348,6 +348,8 @@ development needs.
 Finding dead ends
 ...............................................................................
 
+.. finding_dead_ends_start
+
 If there is a vertices table already built using ``pgr_extractVertices``
 and want the degree of the whole graph rather than a subset, it can be forgo using
 ``pgr_degree`` and work with the ``in_edges`` and ``out_edges`` columns
@@ -359,6 +361,8 @@ The degree of a dead end is 1.
    :start-after: degree_from_table_start
    :end-before: degree_from_table_end
 
+.. finding_dead_ends_end
+
 Finding linear vertices
 ...............................................................................
 

doc/src/migration.rst

@@ -24,6 +24,88 @@ Results can be different because of the changes.
 .. contents:: Contents
    :depth: 2
 
+.. migrate_pgr_analyzeGraph_start
+
+Migration of ``pgr_analyzeGraph``
+-------------------------------------------------------------------------------
+
+Starting from `v3.8.0 <https://docs.pgrouting.org/3.8/en/migration.html>`__
+
+**Before Deprecation:** The following was calculated:
+
+* Number of isolated segments.
+* Number of dead ends.
+* Number of potential gaps found near dead ends.
+* Number of intersections. (between 2 edges)
+
+WHERE
+
+:Graph component: A connected subgraph that is not part of any larger connected
+                  subgraph.
+:Isolated segment: A graph component with only one segment.
+:Dead ends: A vertex that participates in only one edge.
+:gaps: Space between two geometries.
+:Intersection: Is a topological relationship between two geometries.
+
+.. rubric:: Migration.
+
+.. rubric:: Components.
+
+Instead of counting only isolated segments, determine all the components of the
+graph.
+
+Depending of the final application requirements use:
+
+* :doc:`pgr_connectedComponents`
+* :doc:`pgr_strongComponents`
+* :doc:`pgr_biconnectedComponents`
+
+For example:
+
+.. literalinclude:: migration.queries
+   :start-after: --analysis1
+   :end-before: --analysis2
+
+.. rubric:: Dead ends.
+
+Instead of counting the dead ends, determine all the dead ends of the graph
+using :doc:`pgr_degree`.
+
+For example:
+
+.. literalinclude:: migration.queries
+   :start-after: --analysis2
+   :end-before: --analysis3
+
+.. rubric:: Potential gaps near dead ends.
+
+Instead of counting potential gaps between geometries, determine the geometric
+gaps in the graph using :doc:`pgr_findCloseEdges`.
+
+For example:
+
+.. literalinclude:: migration.queries
+   :start-after: --analysis3
+   :end-before: --analysis4
+
+.. rubric::  Topological relationships.
+
+Instead of counting intersections, determine topological relationships between
+geometries.
+
+Several PostGIS functions can be used:
+`ST_Intersects <https://postgis.net/docs/ST_Intersects.html>`__,
+`ST_Crosses <https://postgis.net/docs/ST_Crosses.html>`__,
+`ST_Overlaps <https://postgis.net/docs/ST_Overlaps.html>`__, etc.
+
+For example:
+
+.. literalinclude:: migration.queries
+   :start-after: --analysis4
+   :end-before: --analysis5
+
+.. migrate_pgr_analyzeGraph_end
+
 Migration of ``pgr_aStar``
 -------------------------------------------------------------------------------
 
@@ -35,7 +117,7 @@ Signatures to be migrated:
 * ``pgr_aStar`` (`One to Many`)
 * ``pgr_aStar`` (`Many to One`)
 
-:Before Migration:
+.. rubric:: Before Migration
 
 * Output columns were |old-generic-result|
 

doc/src/pgRouting-concepts.rst

@@ -737,6 +737,8 @@ Disconnected graphs
 
 .. connecting_graph_start
 
+.. disconnected_graph_start
+
 To get the graph connectivity:
 
 .. literalinclude:: concepts.queries
@@ -746,6 +748,8 @@ To get the graph connectivity:
 In this example, the component :math:`2` consists of vertices :math:`\{2, 4\}`
 and both vertices are also part of the dead end result set.
 
+.. disconnected_graph_end
+
 This graph needs to be connected.
 
 .. Note::

doc/src/release_notes.rst

@@ -39,26 +39,38 @@ pgRouting 3.8
 pgRouting 3.8.0 Release Notes
 -------------------------------------------------------------------------------
 
+To see all issues & pull requests closed by this release see the `Git closed
+milestone for 3.8.0
+<https://github.com/pgRouting/pgrouting/issues?utf8=%E2%9C%93&q=milestone%3A%22Release%203.8.0%22>`__
+
 .. rubric:: Promotion to official function of pgRouting.
 
-* pgr_extractVertices
+* `#2772 <https://github.com/pgRouting/pgrouting/issues/2772>`__:
+  pgr_extractVertices
 
   .. include:: pgr_extractVertices.rst
      :start-after: Version 3.8.0
      :end-before: .. rubric
 
-* pgr_degree
+* `#2760 <https://github.com/pgRouting/pgrouting/issues/2760>`__:
+  pgr_degree
 
   .. include:: pgr_degree.rst
      :start-after: Version 3.8.0
      :end-before: .. rubric
 
-* pgr_findCloseEdges
+* `#2774 <https://github.com/pgRouting/pgrouting/issues/2774>`__:
+  pgr_findCloseEdges
 
   .. include:: pgr_findCloseEdges.rst
      :start-after: Version 3.8.0
      :end-before: .. rubric
 
+.. rubric:: Deprecation of functions.
+
+* `#2753 <https://github.com/pgRouting/pgrouting/issues/2753>`__:
+  pgr_analyzeGraph
+
 .. rubric:: Official functions changes
 
 * `#2786 <https://github.com/pgRouting/pgrouting/issues/2786>`__: pgr_contraction

doc/topology/pgr_analyzeGraph.rst

@@ -13,17 +13,24 @@
 
 |
 
-``pgr_analyzeGraph``
+``pgr_analyzeGraph`` -- Deprecated since 3.8.0
 ===============================================================================
 
 ``pgr_analyzeGraph`` — Analyzes the network topology.
 
 .. rubric:: Availability
 
+* Version 3.8.0
+
+  * Deprecated function.
+
 * Version 2.0.0
 
   * Official function.
 
+.. include:: migration.rst
+   :start-after: migrate_pgr_analyzeGraph_start
+   :end-before: migrate_pgr_analyzeGraph_end
 
 Description
 -------------------------------------------------------------------------------

docqueries/src/migration.pg

@@ -377,3 +377,27 @@ FROM pgr_primDD(
   'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
   ARRAY[9, 6], 3.5);
 /* --primDD5 */
+
+/* --analysis1 */
+SELECT *
+FROM pgr_connectedComponents(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+);
+/* --analysis2 */
+SELECT *
+FROM pgr_degree($$SELECT id, source, target FROM edges$$)
+WHERE degree = 1;
+/* --analysis3*/
+WITH
+deadends AS (
+  SELECT id,geom, (in_edges || out_edges)[1] as inhere
+  FROM vertices where array_length(in_edges || out_edges, 1) = 1),
+results AS (
+  SELECT (pgr_findCloseEdges('SELECT id, geom FROM edges WHERE id != ' || inhere , geom, 0.001)).*
+  FROM deadends)
+SELECT d.id, edge_id, distance, st_AsText(geom) AS point, st_asText(edge) edge
+FROM results JOIN deadends d USING (geom);
+/* --analysis4*/
+SELECT e1.id AS id1, e2.id AS id2
+FROM edges e1, edges e2 WHERE e1 < e2 AND st_crosses(e1.geom, e2.geom);
+/* --analysis5*/

docqueries/src/migration.result

@@ -1241,5 +1241,70 @@ FROM pgr_primDD(
 (17 rows)
 
 /* --primDD5 */
+/* --analysis1 */
+SELECT *
+FROM pgr_connectedComponents(
+  'SELECT id, source, target, cost, reverse_cost FROM edges'
+);
+ seq | component | node
+-----+-----------+------
+   1 |         1 |    1
+   2 |         1 |    3
+   3 |         1 |    5
+   4 |         1 |    6
+   5 |         1 |    7
+   6 |         1 |    8
+   7 |         1 |    9
+   8 |         1 |   10
+   9 |         1 |   11
+  10 |         1 |   12
+  11 |         1 |   15
+  12 |         1 |   16
+  13 |         1 |   17
+  14 |         2 |    2
+  15 |         2 |    4
+  16 |        13 |   13
+  17 |        13 |   14
+(17 rows)
+
+/* --analysis2 */
+SELECT *
+FROM pgr_degree($$SELECT id, source, target FROM edges$$)
+WHERE degree = 1;
+ node | degree
+------+--------
+    9 |      1
+    5 |      1
+    4 |      1
+   14 |      1
+   13 |      1
+    2 |      1
+    1 |      1
+(7 rows)
+
+/* --analysis3*/
+WITH
+deadends AS (
+  SELECT id,geom, (in_edges || out_edges)[1] as inhere
+  FROM vertices where array_length(in_edges || out_edges, 1) = 1),
+results AS (
+  SELECT (pgr_findCloseEdges('SELECT id, geom FROM edges WHERE id != ' || inhere , geom, 0.001)).*
+  FROM deadends)
+SELECT d.id, edge_id, distance, st_AsText(geom) AS point, st_asText(edge) edge
+FROM results JOIN deadends d USING (geom);
+ id | edge_id |     distance      |           point           |                 edge
+----+---------+-------------------+---------------------------+--------------------------------------
+  4 |      14 | 1.00008890058e-12 | POINT(1.999999999999 3.5) | LINESTRING(1.999999999999 3.5,2 3.5)
+(1 row)
+
+/* --analysis4*/
+SELECT e1.id AS id1, e2.id AS id2
+FROM edges e1, edges e2 WHERE e1 < e2 AND st_crosses(e1.geom, e2.geom);
+ id1 | id2
+-----+-----
+  13 |  18
+(1 row)
+
+/* --analysis5*/
 ROLLBACK;
 ROLLBACK