refactor: move optional arguments of similarity-efficiency functions behind the ellipsis

R/assortativity.R

@@ -239,13 +239,37 @@ assortativity_legacy <- function(
 #'   with [as.integer()]. Character vectors are converted to integers using
 #'   [as.factor()].
 #' @rdname assortativity
+#' @inheritParams rlang::args_dots_empty
 #' @export
 assortativity_nominal <- function(
   graph,
   types,
+  ...,
   directed = TRUE,
   normalized = TRUE
 ) {
+  # BEGIN GENERATED ARG_HANDLE: assortativity_nominal, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(directed = directed, normalized = normalized),
+      recover_new = c("directed", "normalized"),
+      recover_old = c("directed", "normalized"),
+      match_names = c("directed", "normalized"),
+      match_to = c("directed", "normalized"),
+      defaults = list(directed = TRUE, normalized = TRUE),
+      head_args = c("graph", "types"),
+      fn_name = "assortativity_nominal"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # Convert character types to factor then to integer for categorical data
   if (is.character(types)) {
     types <- as.integer(as.factor(types))
@@ -260,8 +284,35 @@ assortativity_nominal <- function(
 }
 
 #' @rdname assortativity
+#' @inheritParams rlang::args_dots_empty
 #' @export
-assortativity_degree <- function(graph, directed = TRUE) {
+assortativity_degree <- function(
+  graph,
+  ...,
+  directed = TRUE
+) {
+  # BEGIN GENERATED ARG_HANDLE: assortativity_degree, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(directed = directed),
+      recover_new = c("directed"),
+      recover_old = c("directed"),
+      match_names = c("directed"),
+      match_to = c("directed"),
+      defaults = list(directed = TRUE),
+      head_args = c("graph"),
+      fn_name = "assortativity_degree"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   assortativity_degree_impl(
     graph = graph,
     directed = directed

R/cycles.R

@@ -31,6 +31,7 @@
 #' a specific cycle.
 #'
 #' @param graph The input graph.
+#' @inheritParams rlang::args_dots_empty
 #' @param mode Character constant specifying how to handle directed graphs.
 #'   `out` follows edge directions, `in` follows edges in the reverse direction,
 #'   and `all` ignores edge directions. Ignored in undirected graphs.

R/efficiency.R

@@ -37,6 +37,7 @@
 #' efficiency above.
 #'
 #' @param graph The graph to analyze.
+#' @inheritParams rlang::args_dots_empty
 #' @param weights The edge weights. All edge weights must be non-negative;
 #'   additionally, no edge weight may be NaN. If it is `NULL` (the default)
 #'   and the graph has a `weight` edge attribute, then it is used automatically.
@@ -66,7 +67,34 @@
 #' g <- make_graph("zachary")
 #' global_efficiency(g)
 #' average_local_efficiency(g)
-global_efficiency <- function(graph, weights = NULL, directed = TRUE) {
+global_efficiency <- function(
+  graph,
+  ...,
+  weights = NULL,
+  directed = TRUE
+) {
+  # BEGIN GENERATED ARG_HANDLE: global_efficiency, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(weights = weights, directed = directed),
+      recover_new = c("weights", "directed"),
+      recover_old = c("weights", "directed"),
+      match_names = c("weights", "directed"),
+      match_to = c("weights", "directed"),
+      defaults = list(weights = NULL, directed = TRUE),
+      head_args = c("graph"),
+      fn_name = "global_efficiency"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   global_efficiency_impl(
     graph = graph,
     weights = weights,
@@ -75,14 +103,42 @@ global_efficiency <- function(graph, weights = NULL, directed = TRUE) {
 }
 
 #' @rdname global_efficiency
+#' @inheritParams rlang::args_dots_empty
 #' @export
 local_efficiency <- function(
   graph,
   vids = V(graph),
+  ...,
   weights = NULL,
   directed = TRUE,
   mode = c("all", "out", "in", "total")
 ) {
+  # BEGIN GENERATED ARG_HANDLE: local_efficiency, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(weights = weights, directed = directed, mode = mode),
+      recover_new = c("weights", "directed", "mode"),
+      recover_old = c("weights", "directed", "mode"),
+      match_names = c("weights", "directed", "mode"),
+      match_to = c("weights", "directed", "mode"),
+      defaults = list(
+        weights = NULL,
+        directed = TRUE,
+        mode = c("all", "out", "in", "total")
+      ),
+      head_args = c("graph", "vids"),
+      fn_name = "local_efficiency"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   local_efficiency_impl(
     graph = graph,
     vids = vids,
@@ -93,13 +149,41 @@ local_efficiency <- function(
 }
 
 #' @rdname global_efficiency
+#' @inheritParams rlang::args_dots_empty
 #' @export
 average_local_efficiency <- function(
   graph,
+  ...,
   weights = NULL,
   directed = TRUE,
   mode = c("all", "out", "in", "total")
 ) {
+  # BEGIN GENERATED ARG_HANDLE: average_local_efficiency, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(weights = weights, directed = directed, mode = mode),
+      recover_new = c("weights", "directed", "mode"),
+      recover_old = c("weights", "directed", "mode"),
+      match_names = c("weights", "directed", "mode"),
+      match_to = c("weights", "directed", "mode"),
+      defaults = list(
+        weights = NULL,
+        directed = TRUE,
+        mode = c("all", "out", "in", "total")
+      ),
+      head_args = c("graph"),
+      fn_name = "average_local_efficiency"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   average_local_efficiency_impl(
     graph = graph,
     weights = weights,

R/similarity.R

@@ -27,6 +27,7 @@
 #'
 #' @param graph The input graph.
 #' @param vids The vertex IDs for which the similarity is calculated.
+#' @inheritParams rlang::args_dots_empty
 #' @param mode The type of neighboring vertices to use for the calculation,
 #'   possible values: \sQuote{`out`}, \sQuote{`in`},
 #'   \sQuote{`all`}.
@@ -52,6 +53,7 @@
 similarity <- function(
   graph,
   vids = V(graph),
+  ...,
   mode = c(
     "all",
     "out",
@@ -65,6 +67,32 @@ similarity <- function(
     "invlogweighted"
   )
 ) {
+  # BEGIN GENERATED ARG_HANDLE: similarity, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(mode = mode, loops = loops, method = method),
+      recover_new = c("mode", "loops", "method"),
+      recover_old = c("mode", "loops", "method"),
+      match_names = c("mode", "loops", "method"),
+      match_to = c("mode", "loops", "method"),
+      defaults = list(
+        mode = c("all", "out", "in", "total"),
+        loops = FALSE,
+        method = c("jaccard", "dice", "invlogweighted")
+      ),
+      head_args = c("graph", "vids"),
+      fn_name = "similarity"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   method <- igraph_match_arg(method)
   if (method == "jaccard") {
     similarity_jaccard_impl(

tests/testthat/test-assortativity.R

@@ -83,3 +83,47 @@ test_that("nominal assortativity works with character types", {
   result_numeric <- assortativity_nominal(g, types = numeric_from_char)
   expect_equal(result3, result_numeric)
 })
+
+# ---- ellipsis migration: argument coverage ----------------------------
+
+test_that("assortativity_degree() covers directed", {
+  g <- make_star(6, mode = "out")
+
+  # A star is perfectly disassortative when treated as undirected,
+  # while the directed variant is undefined for an out-star.
+  expect_equal(assortativity_degree(g, directed = FALSE), -1)
+  expect_true(is.nan(assortativity_degree(g)))
+})
+
+test_that("assortativity_degree() recovers legacy positional arguments", {
+  g <- make_star(6, mode = "out")
+
+  lifecycle::expect_deprecated(
+    res <- assortativity_degree(g, FALSE)
+  )
+  expect_identical(res, assortativity_degree(g, directed = FALSE))
+})
+
+test_that("assortativity_nominal() covers directed and normalized", {
+  # Two directed triangles joined by a single bridge edge.
+  g <- make_graph(c(1, 2, 2, 3, 3, 1, 4, 5, 5, 6, 6, 4, 3, 4), directed = TRUE)
+  types <- c(1, 1, 1, 2, 2, 2)
+
+  # The non-normalized undirected value is the modularity of the two groups.
+  expect_equal(
+    assortativity_nominal(g, types, directed = FALSE, normalized = FALSE),
+    5 / 14
+  )
+  # Edge directions change the non-normalized value under the directed default.
+  expect_equal(assortativity_nominal(g, types, normalized = FALSE), 18 / 49)
+})
+
+test_that("assortativity_nominal() recovers legacy positional arguments", {
+  g <- make_graph(c(1, 2, 2, 3, 3, 1, 4, 5, 5, 6, 6, 4, 3, 4), directed = TRUE)
+  types <- c(1, 1, 1, 2, 2, 2)
+
+  lifecycle::expect_deprecated(
+    res <- assortativity_nominal(g, types, FALSE)
+  )
+  expect_identical(res, assortativity_nominal(g, types, directed = FALSE))
+})