refactor: Rename algo to algorithm in page_rank(), feedback_arc_set() and feedback_vertex_set()

R/centrality.R

@@ -26,6 +26,8 @@ subgraph.centrality <- function(graph, diag = FALSE) {
 #' `page.rank()` was renamed to [page_rank()] to create a more
 #' consistent API.
 #' @inheritParams page_rank
+#' @param algo `r lifecycle::badge("deprecated")` Use `algorithm` in
+#'   [page_rank()] instead.
 #' @keywords internal
 #' @export
 page.rank <- function(
@@ -42,7 +44,7 @@ page.rank <- function(
   lifecycle::deprecate_warn("2.0.0", "page.rank()", "page_rank()")
   page_rank(
     graph = graph,
-    algo = algo,
+    algorithm = algo,
     vids = vids,
     directed = directed,
     damping = damping,
@@ -1884,7 +1886,7 @@ hub_score <- function(
 #'
 #' @param graph The graph object.
 #' @inheritParams rlang::args_dots_empty
-#' @param algo Character scalar, which implementation to use to carry out the
+#' @param algorithm Character scalar, which implementation to use to carry out the
 #'   calculation. The default is `"prpack"`, which uses the PRPACK library
 #'   (<https://github.com/dgleich/prpack>) to calculate PageRank scores
 #'   by solving a set of linear equations. This is a new implementation in igraph
@@ -1953,7 +1955,7 @@ hub_score <- function(
 page_rank <- function(
   graph,
   ...,
-  algo = c("prpack", "arpack"),
+  algorithm = c("prpack", "arpack"),
   vids = NULL,
   directed = TRUE,
   damping = 0.85,
@@ -1964,7 +1966,7 @@ page_rank <- function(
   # BEGIN GENERATED ARG_HANDLE: page_rank, do not edit, see tools/generate-migrations.R
   # fmt: skip
   if (...length() > 0L) {
-    .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("d"))
+    .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("a", "al", "alg", "d"))
     if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn page_rank}.")
     # Pre-3.0.0 signature: page_rank(graph, algo, vids, directed, damping, personalized, weights, options)
     .old_signature <- function(algo, vids, directed, damping, personalized, weights, options, ...) {
@@ -1975,7 +1977,7 @@ page_rank <- function(
         cli::cli_abort(base::c("Unexpected argument passed to {.fn page_rank}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())
       }
       base::c(
-        if (!base::missing(algo)) base::list(algo = algo),
+        if (!base::missing(algo)) base::list(algorithm = algo),
         if (!base::missing(vids)) base::list(vids = vids),
         if (!base::missing(directed)) base::list(directed = directed),
         if (!base::missing(damping)) base::list(damping = damping),
@@ -1988,7 +1990,7 @@ page_rank <- function(
     if (base::length(.arg_handle) > 0L) {
       .arg_names <- base::names(.arg_handle)
       .arg_conflict <- base::intersect(.arg_names, base::c(
-        if (!base::missing(algo)) "algo",
+        if (!base::missing(algorithm)) "algorithm",
         if (!base::missing(vids)) "vids",
         if (!base::missing(directed)) "directed",
         if (!base::missing(damping)) "damping",
@@ -2002,7 +2004,7 @@ page_rank <- function(
         "3.0.0",
         what = base::I("Calling `page_rank()` with positional or abbreviated arguments"),
         details = base::c(
-          i = base::paste0("Detected call:  page_rank(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"),
+          i = base::paste0("Detected call:  page_rank(", base::paste(base::c("graph", base::c(algorithm = "algo", vids = "vids", directed = "directed", damping = "damping", personalized = "personalized", weights = "weights", options = "options")[.arg_names]), collapse = ", "), ")"),
           i = base::paste0("Use instead:    page_rank(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
         )
       )
@@ -2016,7 +2018,7 @@ page_rank <- function(
 
   personalized_pagerank_impl(
     graph = graph,
-    algo = algo,
+    algo = algorithm,
     vids = vids,
     directed = directed,
     damping = damping,

R/structural-properties.R

@@ -3216,7 +3216,7 @@ topo_sort <- function(
 #'   `NULL`, then the edge attribute is used automatically. The goal of
 #'   the feedback arc set problem is to find a feedback arc set with the smallest
 #'   total weight.
-#' @param algo Specifies the algorithm to use. \dQuote{`exact_ip`} solves
+#' @param algorithm Specifies the algorithm to use. \dQuote{`exact_ip`} solves
 #'   the feedback arc set problem with an exact integer programming algorithm that
 #'   guarantees that the total weight of the removed edges is as small as possible.
 #'   \dQuote{`approx_eades`} uses a fast (linear-time) approximation
@@ -3236,16 +3236,18 @@ topo_sort <- function(
 #'
 #' g <- sample_gnm(20, 40, directed = TRUE)
 #' feedback_arc_set(g)
-#' feedback_arc_set(g, algo = "approx_eades")
+#' feedback_arc_set(g, algorithm = "approx_eades")
 feedback_arc_set <- function(
   graph,
   ...,
   weights = NULL,
-  algo = c("approx_eades", "exact_ip")
+  algorithm = c("approx_eades", "exact_ip")
 ) {
   # BEGIN GENERATED ARG_HANDLE: feedback_arc_set, do not edit, see tools/generate-migrations.R
   # fmt: skip
   if (...length() > 0L) {
+    .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("a", "al", "alg"))
+    if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn feedback_arc_set}.")
     # Pre-3.0.0 signature: feedback_arc_set(graph, weights, algo)
     .old_signature <- function(weights, algo, ...) {
       if (...length() > 0L) {
@@ -3256,23 +3258,23 @@ feedback_arc_set <- function(
       }
       base::c(
         if (!base::missing(weights)) base::list(weights = weights),
-        if (!base::missing(algo)) base::list(algo = algo)
+        if (!base::missing(algo)) base::list(algorithm = algo)
       )
     }
     .arg_handle <- .old_signature(...)
     if (base::length(.arg_handle) > 0L) {
       .arg_names <- base::names(.arg_handle)
       .arg_conflict <- base::intersect(.arg_names, base::c(
         if (!base::missing(weights)) "weights",
-        if (!base::missing(algo)) "algo"
+        if (!base::missing(algorithm)) "algorithm"
       ))
       if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn feedback_arc_set} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))
       base::list2env(.arg_handle, base::environment())
       lifecycle::deprecate_soft(
         "3.0.0",
         what = base::I("Calling `feedback_arc_set()` with positional or abbreviated arguments"),
         details = base::c(
-          i = base::paste0("Detected call:  feedback_arc_set(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"),
+          i = base::paste0("Detected call:  feedback_arc_set(", base::paste(base::c("graph", base::c(weights = "weights", algorithm = "algo")[.arg_names]), collapse = ", "), ")"),
           i = base::paste0("Use instead:    feedback_arc_set(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
         )
       )
@@ -3283,7 +3285,7 @@ feedback_arc_set <- function(
   feedback_arc_set_impl(
     graph = graph,
     weights = weights,
-    algo = algo
+    algo = algorithm
   )
 }
 
@@ -3303,7 +3305,7 @@ feedback_arc_set <- function(
 #'   `NULL`, then the vertex attribute is used automatically. The goal of
 #'   the feedback vertex set problem is to find a feedback vertex set with
 #'   the smallest total weight.
-#' @param algo Specifies the algorithm to use. Currently, \dQuote{`exact_ip`},
+#' @param algorithm Specifies the algorithm to use. Currently, \dQuote{`exact_ip`},
 #'   which solves the feedback vertex set problem with an exact integer
 #'   programming approach, is the only option.
 #' @return A vertex sequence (by default, but see the `return.vs.es` option
@@ -3320,11 +3322,13 @@ feedback_vertex_set <- function(
   graph,
   ...,
   weights = NULL,
-  algo = c("exact_ip")
+  algorithm = c("exact_ip")
 ) {
   # BEGIN GENERATED ARG_HANDLE: feedback_vertex_set, do not edit, see tools/generate-migrations.R
   # fmt: skip
   if (...length() > 0L) {
+    .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("a", "al", "alg"))
+    if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn feedback_vertex_set}.")
     # Pre-3.0.0 signature: feedback_vertex_set(graph, weights, algo)
     .old_signature <- function(weights, algo, ...) {
       if (...length() > 0L) {
@@ -3335,23 +3339,23 @@ feedback_vertex_set <- function(
       }
       base::c(
         if (!base::missing(weights)) base::list(weights = weights),
-        if (!base::missing(algo)) base::list(algo = algo)
+        if (!base::missing(algo)) base::list(algorithm = algo)
       )
     }
     .arg_handle <- .old_signature(...)
     if (base::length(.arg_handle) > 0L) {
       .arg_names <- base::names(.arg_handle)
       .arg_conflict <- base::intersect(.arg_names, base::c(
         if (!base::missing(weights)) "weights",
-        if (!base::missing(algo)) "algo"
+        if (!base::missing(algorithm)) "algorithm"
       ))
       if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn feedback_vertex_set} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))
       base::list2env(.arg_handle, base::environment())
       lifecycle::deprecate_soft(
         "3.0.0",
         what = base::I("Calling `feedback_vertex_set()` with positional or abbreviated arguments"),
         details = base::c(
-          i = base::paste0("Detected call:  feedback_vertex_set(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"),
+          i = base::paste0("Detected call:  feedback_vertex_set(", base::paste(base::c("graph", base::c(weights = "weights", algorithm = "algo")[.arg_names]), collapse = ", "), ")"),
           i = base::paste0("Use instead:    feedback_vertex_set(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
         )
       )
@@ -3362,7 +3366,7 @@ feedback_vertex_set <- function(
   feedback_vertex_set_impl(
     graph = graph,
     weights = weights,
-    algo = algo
+    algo = algorithm
   )
 }
 

tests/testthat/_snaps/centrality.md

@@ -59,3 +59,13 @@
       Error in `arpack()`:
       ! Can't use unkown ARPACK options: unknown_thing1, unknown_thing2
 
+# page_rank(algo = ) is deprecated but still works
+
+    Code
+      res_legacy <- page_rank(star, algo = "prpack")
+    Condition
+      Warning:
+      Calling `page_rank()` with positional or abbreviated arguments was deprecated in igraph 3.0.0.
+      i Detected call: page_rank(graph, algo)
+      i Use instead: page_rank(graph, algorithm = )
+

tests/testthat/test-centrality.R

@@ -1074,12 +1074,12 @@ test_that("page_rank() covers migrated tail args and positional recovery", {
   # The weight attribute is a decoy that the explicit `weights` must override.
   E(star)$weight <- c(10, rep(1, 8))
 
-  # `algo` keeps its default value:
+  # `algorithm` keeps its default value:
   # non-default values select the legacy ARPACK implementation,
   # and `options` is only consumed by that implementation.
   res <- page_rank(
     star,
-    algo = "prpack",
+    algorithm = "prpack",
     vids = V(star)[1:5],
     directed = FALSE,
     damping = 0.9,
@@ -1106,7 +1106,16 @@ test_that("page_rank() covers migrated tail args and positional recovery", {
   lifecycle::expect_deprecated(
     res_legacy <- page_rank(star, "prpack")
   )
-  expect_identical(res_legacy, page_rank(star, algo = "prpack"))
+  expect_identical(res_legacy, page_rank(star, algorithm = "prpack"))
+})
+
+test_that("page_rank(algo = ) is deprecated but still works", {
+  rlang::local_options(lifecycle_verbosity = "warning")
+  star <- make_star(10, mode = "undirected")
+  expect_snapshot(
+    res_legacy <- page_rank(star, algo = "prpack")
+  )
+  expect_identical(res_legacy, page_rank(star, algorithm = "prpack"))
 })
 
 test_that("strength() covers migrated tail args and positional recovery", {

tests/testthat/test-structural-properties.R

@@ -1398,11 +1398,21 @@ test_that("feedback_arc_set() tail arguments and legacy positional recovery", {
   g <- make_ring(4, directed = TRUE)
 
   # The exact algorithm removes the cheapest edge of the single cycle.
-  fas <- feedback_arc_set(g, weights = c(4, 3, 2, 1), algo = "exact_ip")
+  fas <- feedback_arc_set(g, weights = c(4, 3, 2, 1), algorithm = "exact_ip")
   expect_equal(as.numeric(fas), 4)
 
   lifecycle::expect_deprecated(res <- feedback_arc_set(g, c(4, 3, 2, 1)))
   expect_equal(res, feedback_arc_set(g, weights = c(4, 3, 2, 1)))
+
+  # The legacy `algo` name is recovered as `algorithm`.
+  lifecycle::expect_deprecated(
+    res_legacy <- feedback_arc_set(
+      g,
+      weights = c(4, 3, 2, 1),
+      algo = "exact_ip"
+    )
+  )
+  expect_equal(res_legacy, fas)
 })
 
 test_that("feedback_vertex_set() tail arguments and legacy positional recovery", {
@@ -1411,11 +1421,21 @@ test_that("feedback_vertex_set() tail arguments and legacy positional recovery",
   g <- make_ring(4, directed = TRUE)
 
   # The cheapest vertex of the single cycle is removed.
-  fvs <- feedback_vertex_set(g, weights = c(4, 3, 2, 1), algo = "exact_ip")
+  fvs <- feedback_vertex_set(g, weights = c(4, 3, 2, 1), algorithm = "exact_ip")
   expect_equal(as.numeric(fvs), 4)
 
   lifecycle::expect_deprecated(res <- feedback_vertex_set(g, c(4, 3, 2, 1)))
   expect_equal(res, feedback_vertex_set(g, weights = c(4, 3, 2, 1)))
+
+  # The legacy `algo` name is recovered as `algorithm`.
+  lifecycle::expect_deprecated(
+    res_legacy <- feedback_vertex_set(
+      g,
+      weights = c(4, 3, 2, 1),
+      algo = "exact_ip"
+    )
+  )
+  expect_equal(res_legacy, fvs)
 })
 
 test_that("girth() tail arguments and legacy positional recovery", {

tools/migrations/centrality.R

@@ -88,7 +88,7 @@ migrations <- list(
   page_rank = list(
     old = function(
       graph,
-      algo,
+      algo = algorithm,
       vids,
       directed,
       damping,
@@ -99,7 +99,7 @@ migrations <- list(
     new = function(
       graph,
       ...,
-      algo = c("prpack", "arpack"),
+      algorithm = c("prpack", "arpack"),
       vids = NULL,
       directed = TRUE,
       damping = 0.85,