fix: Add deprecation warnings for inconsistent mode parameter defaults

NEWS.md

@@ -2,6 +2,13 @@
 
 # igraph 2.2.1.9002
 
+## Breaking changes (future)
+
+- The default value of the `mode` parameter will change from `"all"` to `"out"` in a future version for the following functions: `distances()`, `degree()`, `strength()`, `eccentricity()`, `radius()`, `graph_center()`, `ego()`, `ego_size()`, and `make_ego_graph()`.
+  This change makes the default behavior more intuitive by respecting edge directions in directed graphs instead of ignoring them.
+  A deprecation warning is now issued when these functions are called on directed graphs without explicitly specifying the `mode` parameter.
+  To prepare for this change and avoid warnings, please specify `mode` explicitly in your code.
+
 ## Bug fixes
 
 - Use `LC_ALL=C` instead of `LOCALE=C` in `deps.mk` (#2446, #2447).

R/centrality.R

@@ -1408,6 +1408,18 @@ strength <- function(
   loops = TRUE,
   weights = NULL
 ) {
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "strength(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   strength_impl(
     graph = graph,
     vids = vids,

R/embedding.R

@@ -108,7 +108,7 @@ embed_adjacency_matrix <- function(
   weights = NULL,
   which = c("lm", "la", "sa"),
   scaled = TRUE,
-  cvec = strength(graph, weights = weights) / (vcount(graph) - 1),
+  cvec = strength(graph, weights = weights, mode = "all") / (vcount(graph) - 1),
   options = arpack_defaults()
 ) {
   adjacency_spectral_embedding_impl(

R/paths.R

@@ -306,6 +306,18 @@ eccentricity <- function(
     }
   }
 
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "eccentricity(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   eccentricity_dijkstra_impl(
     graph = graph,
     vids = vids,
@@ -365,6 +377,18 @@ radius <- function(
     }
   }
 
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "radius(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   radius_dijkstra_impl(
     graph = graph,
     weights = weights,
@@ -405,6 +429,18 @@ graph_center <- function(
   weights = NULL,
   mode = c("all", "out", "in", "total")
 ) {
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "graph_center(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   graph_center_dijkstra_impl(
     graph = graph,
     weights = weights,

R/structural-properties.R

@@ -919,6 +919,19 @@ degree <- function(
   normalized = FALSE
 ) {
   ensure_igraph(graph)
+
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "degree(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   v <- as_igraph_vs(graph, v)
   mode <- igraph.match.arg(mode)
 
@@ -1205,6 +1218,18 @@ distances <- function(
 ) {
   ensure_igraph(graph)
 
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "distances(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   # make sure that the lower-level function in C gets mode == "out"
   # unconditionally when the graph is undirected; this is used for
   # the selection of Johnson's algorithm in automatic mode
@@ -2054,6 +2079,19 @@ ego_size <- function(
   mindist = 0
 ) {
   ensure_igraph(graph)
+
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "ego_size(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   mode <- igraph.match.arg(mode)
   mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3)
   mindist <- as.numeric(mindist)
@@ -2168,6 +2206,19 @@ ego <- function(
   mindist = 0
 ) {
   ensure_igraph(graph)
+
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "ego(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   mode <- igraph.match.arg(mode)
   mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3)
   mindist <- as.numeric(mindist)
@@ -2203,6 +2254,19 @@ make_ego_graph <- function(
   mindist = 0
 ) {
   ensure_igraph(graph)
+
+  # Warn about upcoming change in default mode parameter
+  if (missing(mode) && is_directed(graph)) {
+    lifecycle::deprecate_soft(
+      "2.1.0",
+      "make_ego_graph(mode =)",
+      details = paste(
+        "The default value of `mode` will change from \"all\" to \"out\" in a future version.",
+        "Please specify `mode` explicitly to avoid this warning and ensure consistent behavior."
+      )
+    )
+  }
+
   mode <- igraph.match.arg(mode)
   mode <- switch(mode, "out" = 1L, "in" = 2L, "all" = 3L)
   mindist <- as.numeric(mindist)

tests/testthat/test-conversion.R

@@ -1,19 +1,19 @@
 test_that("as_directed works", {
   gnp_undirected <- sample_gnp(100, 2 / 100)
   gnp_mutual <- as_directed(gnp_undirected, mode = "mutual")
-  expect_equal(degree(gnp_undirected), degree(gnp_mutual) / 2)
+  expect_equal(degree(gnp_undirected), degree(gnp_mutual, mode = "all") / 2)
   expect_isomorphic(gnp_undirected, as_undirected(gnp_mutual))
 
   gnp_arbitrary <- as_directed(gnp_undirected, mode = "arbitrary")
-  expect_equal(degree(gnp_undirected), degree(gnp_arbitrary))
+  expect_equal(degree(gnp_undirected), degree(gnp_arbitrary, mode = "all"))
   expect_isomorphic(gnp_undirected, as_undirected(gnp_arbitrary))
 
   gnp_random <- as_directed(gnp_undirected, mode = "random")
-  expect_equal(degree(gnp_undirected), degree(gnp_random))
+  expect_equal(degree(gnp_undirected), degree(gnp_random, mode = "all"))
   expect_isomorphic(gnp_undirected, as_undirected(gnp_random))
 
   gnp_acyclic <- as_directed(gnp_undirected, mode = "acyclic")
-  expect_equal(degree(gnp_undirected), degree(gnp_acyclic))
+  expect_equal(degree(gnp_undirected), degree(gnp_acyclic, mode = "all"))
   expect_isomorphic(gnp_undirected, as_undirected(gnp_acyclic))
 })