chore: deprecate scale argument of centr_eigen() and centr_eigen_tmax()

R/centralization.R

@@ -448,8 +448,8 @@ centr_clo_tmax <- centralization_closeness_tmax_impl
 #' @param graph The input graph.
 #' @param directed logical scalar, whether to use directed shortest paths for
 #'   calculating eigenvector centrality.
-#' @param scale Whether to rescale the eigenvector centrality scores, such that
-#'   the maximum score is one.
+#' @param scale `r lifecycle::badge("deprecated")` Ignored. Computing
+#' eigenvector centralization requires normalized eigenvector centrality scores.
 #' @param options This is passed to [eigen_centrality()], the options
 #'   for the ARPACK eigensolver.
 #' @param normalized Logical scalar. Whether to normalize the graph level
@@ -481,7 +481,28 @@ centr_clo_tmax <- centralization_closeness_tmax_impl
 #' centr_eigen(g0)$centralization
 #' centr_eigen(g1)$centralization
 #' @cdocs igraph_centralization_eigenvector_centrality
-centr_eigen <- centralization_eigenvector_centrality_impl
+centr_eigen <- function(graph,
+                        directed = FALSE,
+                        scale = deprecated(),
+                        options = arpack_defaults(),
+                        normalized = TRUE) {
+
+  if (lifecycle::is_present(scale)) {
+    lifecycle::deprecate_soft(
+      "2.1.3",
+      "centr_eigen(scale = )",
+      details = "The function always behaves as if `scale` were TRUE.
+      The argument will be removed in the future."
+    )
+  }
+
+  centralization_eigenvector_centrality_impl(
+    graph = graph,
+    directed = directed,
+    options = options,
+    normalized = normalized
+  )
+}
 
 #' Theoretical maximum for eigenvector centralization
 #'
@@ -493,8 +514,8 @@ centr_eigen <- centralization_eigenvector_centrality_impl
 #'   given.
 #' @param directed logical scalar, whether to consider edge directions
 #'   during the calculation. Ignored in undirected graphs.
-#' @param scale Whether to rescale the eigenvector centrality scores,
-#'   such that the maximum score is one.
+#' @param scale `r lifecycle::badge("deprecated")` Ignored. Computing
+#' eigenvector centralization requires normalized eigenvector centrality scores.
 #' @return Real scalar, the theoretical maximum (unnormalized) graph
 #'   eigenvector centrality score for graphs with given vertex count and
 #'   other parameters.
@@ -510,4 +531,23 @@ centr_eigen <- centralization_eigenvector_centrality_impl
 #'   `/`(centr_eigen_tmax(g))
 #' centr_eigen(g, normalized = TRUE)$centralization
 #' @cdocs igraph_centralization_eigenvector_centrality_tmax
-centr_eigen_tmax <- centralization_eigenvector_centrality_tmax_impl
+centr_eigen_tmax <- function(graph = NULL,
+                             nodes = 0,
+                             directed = FALSE,
+                               scale = deprecated()) {
+
+  if (lifecycle::is_present(scale)) {
+    lifecycle::deprecate_soft(
+      "2.1.3",
+      "centr_eigen_tmax(scale = )",
+      details = "The function always behaves as if `scale` were TRUE.
+      The argument will be removed in the future."
+    )
+  }
+
+  centralization_eigenvector_centrality_tmax_impl(
+    graph = graph,
+    nodes = nodes,
+    directed = directed
+  )
+}

tests/testthat/_snaps/centralization.md

@@ -0,0 +1,27 @@
+# centr_eigen_tmax() deprecated argument
+
+    Code
+      c <- centr_eigen_tmax(g, scale = FALSE)
+    Condition
+      Warning:
+      The `scale` argument of `centr_eigen_tmax()` is deprecated as of igraph 2.1.3.
+      i The function always behaves as if `scale` were TRUE. The argument will be removed in the future.
+
+# centr_eigen() deprecated argument
+
+    Code
+      c <- centr_eigen(g, scale = FALSE)
+    Condition
+      Warning:
+      The `scale` argument of `centr_eigen()` is deprecated as of igraph 2.1.3.
+      i The function always behaves as if `scale` were TRUE. The argument will be removed in the future.
+
+# centr_degree_tmax() deprecated argument
+
+    Code
+      c <- centr_degree_tmax(g)
+    Condition
+      Warning:
+      The `loops` argument of `centr_degree_tmax()` must be explicit as of igraph 2.0.0.
+      i Default value (`FALSE`) will be dropped in next release, add an explicit value for the loops argument.
+

tests/testthat/test-centralization.R

@@ -0,0 +1,47 @@
+test_that("centr_eigen_tmax() works", {
+  withr::local_seed(42)
+  g <- sample_pa(1000, m = 4)
+  expect_equal(centr_eigen_tmax(g), 998)
+})
+
+test_that("centr_eigen_tmax() deprecated argument", {
+  g <- sample_pa(1000, m = 4)
+  expect_snapshot(c <- centr_eigen_tmax(g, scale = FALSE))
+})
+
+test_that("centr_eigen() works", {
+  withr::local_seed(42)
+  g <- sample_pa(1000, m = 4)
+  centr_eigen <- centr_eigen(g)
+  expect_setequal(
+    names(centr_eigen),
+    c("vector", "value", "options", "centralization", "theoretical_max")
+  )
+  expect_equal(centr_eigen$centralization, 0.9432924, tolerance = 1e-06)
+})
+
+test_that("centr_eigen() deprecated argument", {
+  g <- sample_pa(1000, m = 4)
+  expect_snapshot(c <- centr_eigen(g, scale = FALSE))
+})
+
+test_that("centr_degree_tmax() works", {
+  withr::local_seed(42)
+  g <- sample_pa(1000, m = 4)
+  expect_gt(centr_degree_tmax(g, loops = TRUE), 1990000)
+})
+
+test_that("centr_degree_tmax() deprecated argument", {
+  g <- sample_pa(1000, m = 4)
+  expect_snapshot(c <- centr_degree_tmax(g))
+})
+
+test_that("centr_betw() works", {
+  withr::local_seed(42)
+  g <- sample_pa(1000, m = 4)
+  expect_setequal(
+    names(centr_betw(g)),
+    c("res", "centralization", "theoretical_max")
+  )
+  expect_equal(centr_betw(g)$theoretical_max, 996004998)
+})