refactor: Rename vertex-selector arguments to vertices

R/cocitation.R

@@ -27,22 +27,23 @@
 #' both cite, `bibcoupling()` calculates this.
 #'
 #' `cocitation()` calculates the cocitation counts for the vertices in the
-#' `v` argument and all vertices in the graph.
+#' `vertices` argument and all vertices in the graph.
 #'
 #' `bibcoupling()` calculates the bibliographic coupling for vertices in
-#' `v` and all vertices in the graph.
+#' `vertices` and all vertices in the graph.
 #'
 #' Calculating the cocitation or bibliographic coupling for only one vertex
 #' costs the same amount of computation as for all vertices. This might change
 #' in the future.
 #'
 #' @param graph The graph object to analyze
-#' @param v Vertex sequence or numeric vector, the vertex IDs for which the
-#'   cocitation or bibliographic coupling values we want to calculate. The
+#' @param vertices Vertex sequence or numeric vector, the vertex IDs for which
+#'   the cocitation or bibliographic coupling values we want to calculate. The
 #'   default `NULL` selects all vertices.
-#' @return A numeric matrix with `length(v)` lines and
+#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead.
+#' @return A numeric matrix with `length(vertices)` lines and
 #'   `vcount(graph)` columns. Element `(i,j)` contains the cocitation
-#'   or bibliographic coupling for vertices `v[i]` and `j`.
+#'   or bibliographic coupling for vertices `vertices[i]` and `j`.
 #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
 #' @family cocitation
 #' @export
@@ -53,37 +54,67 @@
 #' cocitation(g)
 #' bibcoupling(g)
 #'
-cocitation <- function(graph, v = NULL) {
-  if (is.null(v)) {
-    v <- V(graph)
+cocitation <- function(graph, vertices = NULL, v = deprecated()) {
+  if (lifecycle::is_present(v)) {
+    if (!missing(vertices)) {
+      cli::cli_abort(c(
+        "Argument {.arg vertices} of {.fn cocitation} was supplied more than once.",
+        i = "It was also supplied via its legacy name {.arg v}."
+      ))
+    }
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      "cocitation(v = )",
+      "cocitation(vertices = )"
+    )
+    vertices <- v
+  }
+
+  if (is.null(vertices)) {
+    vertices <- V(graph)
   }
 
   res <- cocitation_impl(
     graph = graph,
-    vids = v
+    vids = vertices
   )
   if (igraph_opt("add.vertex.names") && is_named(graph)) {
-    v <- as_igraph_vs(graph, v)
-    rownames(res) <- vertex_attr(graph, "name", v)
+    vertices <- as_igraph_vs(graph, vertices)
+    rownames(res) <- vertex_attr(graph, "name", vertices)
     colnames(res) <- vertex_attr(graph, "name")
   }
   res
 }
 
 #' @rdname cocitation
 #' @export
-bibcoupling <- function(graph, v = NULL) {
-  if (is.null(v)) {
-    v <- V(graph)
+bibcoupling <- function(graph, vertices = NULL, v = deprecated()) {
+  if (lifecycle::is_present(v)) {
+    if (!missing(vertices)) {
+      cli::cli_abort(c(
+        "Argument {.arg vertices} of {.fn bibcoupling} was supplied more than once.",
+        i = "It was also supplied via its legacy name {.arg v}."
+      ))
+    }
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      "bibcoupling(v = )",
+      "bibcoupling(vertices = )"
+    )
+    vertices <- v
+  }
+
+  if (is.null(vertices)) {
+    vertices <- V(graph)
   }
 
   res <- bibcoupling_impl(
     graph = graph,
-    vids = v
+    vids = vertices
   )
   if (igraph_opt("add.vertex.names") && is_named(graph)) {
-    v <- as_igraph_vs(graph, v)
-    rownames(res) <- vertex_attr(graph, "name", v)
+    vertices <- as_igraph_vs(graph, vertices)
+    rownames(res) <- vertex_attr(graph, "name", vertices)
     colnames(res) <- vertex_attr(graph, "name")
   }
   res

R/cohesive.blocks.R

@@ -472,7 +472,7 @@ print.cohesiveBlocks <- function(x, ...) {
   cs <- 3 +
     2 +
     nchar(length(x)) +
-    max(distances(hierarchy(x), mode = "out", v = 1)) * 3
+    max(distances(hierarchy(x), mode = "out", vertices = 1)) * 3
 
   .plot <- function(b, ind = "") {
     if (b != 1) {

R/efficiency.R

@@ -41,9 +41,10 @@
 #' @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.
-#' @param vids The vertex IDs of the vertices for which the calculation will be done.
+#' @param vertices The vertex IDs of the vertices for which the calculation will be done.
 #'   Applies to the local efficiency calculation only. The default `NULL`
 #'   selects all vertices.
+#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead.
 #' @param directed Logical, whether to consider directed paths. Ignored
 #'   for undirected graphs.
 #' @param mode Specifies how to define the local neighborhood of a vertex in
@@ -123,15 +124,18 @@ global_efficiency <- function(
 #' @export
 local_efficiency <- function(
   graph,
-  vids = NULL,
+  vertices = NULL,
   ...,
   weights = NULL,
   directed = TRUE,
-  mode = c("all", "out", "in", "total")
+  mode = c("all", "out", "in", "total"),
+  vids = deprecated()
 ) {
   # BEGIN GENERATED ARG_HANDLE: local_efficiency, do not edit, see tools/generate-migrations.R
   # fmt: skip
   if (...length() > 0L) {
+    .arg_forbidden <- base::intersect(base::names(base::sys.call()), base::c("v"))
+    if (base::length(.arg_forbidden) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_forbidden)}} matches multiple formal arguments of {.fn local_efficiency}.", i = "Spell out the full argument name."))
     # Pre-3.0.0 signature: local_efficiency(graph, vids, weights, directed, mode)
     .old_signature <- function(weights, directed, mode, ...) {
       if (...length() > 0L) {
@@ -160,21 +164,36 @@ local_efficiency <- function(
         "3.0.0",
         what = base::I("Calling `local_efficiency()` with positional or abbreviated arguments"),
         details = base::c(
-          i = base::paste0("Detected call:  local_efficiency(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"),
-          i = base::paste0("Use instead:    local_efficiency(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
+          i = base::paste0("Detected call:  local_efficiency(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"),
+          i = base::paste0("Use instead:    local_efficiency(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
         )
       )
     }
   }
   # END GENERATED ARG_HANDLE
 
-  if (is.null(vids)) {
-    vids <- V(graph)
+  if (lifecycle::is_present(vids)) {
+    if (!missing(vertices)) {
+      cli::cli_abort(c(
+        "Argument {.arg vertices} of {.fn local_efficiency} was supplied more than once.",
+        i = "It was also supplied via its legacy name {.arg vids}."
+      ))
+    }
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      "local_efficiency(vids = )",
+      "local_efficiency(vertices = )"
+    )
+    vertices <- vids
+  }
+
+  if (is.null(vertices)) {
+    vertices <- V(graph)
   }
 
   local_efficiency_impl(
     graph = graph,
-    vids = vids,
+    vids = vertices,
     weights = weights,
     directed = directed,
     mode = mode

R/indexing.R

@@ -538,9 +538,9 @@ expand.grid.unordered <- function(i, j, loops = FALSE, directed = FALSE) {
     if (missing(i) && missing(j)) {
       todel <- seq_len(ecount(x))
     } else if (missing(j)) {
-      todel <- unlist(incident_edges(x, v = i, mode = "out"))
+      todel <- unlist(incident_edges(x, vertices = i, mode = "out"))
     } else if (missing(i)) {
-      todel <- unlist(incident_edges(x, v = j, mode = "in"))
+      todel <- unlist(incident_edges(x, vertices = j, mode = "in"))
     } else {
       edge_pairs <- expand.grid(i, j)
       edge_ids <- get_edge_ids(x, c(rbind(edge_pairs[, 1], edge_pairs[, 2])))

R/interface.R

@@ -27,7 +27,7 @@ is.directed <- function(graph) {
 delete.vertices <- function(graph, v) {
   # nocov start
   lifecycle::deprecate_warn("2.0.0", "delete.vertices()", "delete_vertices()")
-  delete_vertices(graph = graph, v = v)
+  delete_vertices(graph = graph, vertices = v)
 } # nocov end
 
 #' Delete edges from a graph
@@ -273,7 +273,8 @@ delete_edges <- function(graph, edges) {
 #' Delete vertices from a graph
 #'
 #' @param graph The input graph.
-#' @param v The vertices to remove, a vertex sequence.
+#' @param vertices The vertices to remove, a vertex sequence.
+#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead.
 #' @return The graph, with the vertices removed.
 #'
 #' @family functions for manipulating graph structure
@@ -289,10 +290,25 @@ delete_edges <- function(graph, edges) {
 #'   delete_vertices("B")
 #' g2
 #' V(g2)
-delete_vertices <- function(graph, v) {
+delete_vertices <- function(graph, vertices, v = deprecated()) {
+  if (lifecycle::is_present(v)) {
+    if (!missing(vertices)) {
+      cli::cli_abort(c(
+        "Argument {.arg vertices} of {.fn delete_vertices} was supplied more than once.",
+        i = "It was also supplied via its legacy name {.arg v}."
+      ))
+    }
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      "delete_vertices(v = )",
+      "delete_vertices(vertices = )"
+    )
+    vertices <- v
+  }
+
   delete_vertices_impl(
     graph = graph,
-    vertices = v
+    vertices = vertices
   )
 }
 
@@ -787,7 +803,8 @@ gorder <- vcount
 #' the adjacent vertices for multiple vertices at once.
 #'
 #' @param graph Input graph.
-#' @param v The vertices to query.
+#' @param vertices The vertices to query.
+#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead.
 #' @inheritParams neighbors
 #' @inheritParams rlang::args_dots_empty
 #' @return A list of vertex sequences.
@@ -799,9 +816,10 @@ gorder <- vcount
 #' adjacent_vertices(g, c(1, 34))
 adjacent_vertices <- function(
   graph,
-  v,
+  vertices,
   ...,
-  mode = c("out", "in", "all", "total")
+  mode = c("out", "in", "all", "total"),
+  v = deprecated()
 ) {
   # BEGIN GENERATED ARG_HANDLE: adjacent_vertices, do not edit, see tools/generate-migrations.R
   # fmt: skip
@@ -830,17 +848,32 @@ adjacent_vertices <- function(
         "3.0.0",
         what = base::I("Calling `adjacent_vertices()` with positional or abbreviated arguments"),
         details = base::c(
-          i = base::paste0("Detected call:  adjacent_vertices(", base::paste(base::c("graph", "v", .arg_names), collapse = ", "), ")"),
-          i = base::paste0("Use instead:    adjacent_vertices(", base::paste(base::c("graph", "v", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
+          i = base::paste0("Detected call:  adjacent_vertices(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"),
+          i = base::paste0("Use instead:    adjacent_vertices(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
         )
       )
     }
   }
   # END GENERATED ARG_HANDLE
 
+  if (lifecycle::is_present(v)) {
+    if (!missing(vertices)) {
+      cli::cli_abort(c(
+        "Argument {.arg vertices} of {.fn adjacent_vertices} was supplied more than once.",
+        i = "It was also supplied via its legacy name {.arg v}."
+      ))
+    }
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      "adjacent_vertices(v = )",
+      "adjacent_vertices(vertices = )"
+    )
+    vertices <- v
+  }
+
   ensure_igraph(graph)
 
-  vv <- as_igraph_vs(graph, v) - 1
+  vv <- as_igraph_vs(graph, vertices) - 1
   mode <- switch(match.arg(mode), "out" = 1, "in" = 2, "all" = 3, "total" = 3)
 
   on.exit(.Call(Rx_igraph_finalizer))
@@ -865,7 +898,8 @@ adjacent_vertices <- function(
 #' queries multiple vertices at once.
 #'
 #' @param graph Input graph.
-#' @param v The vertices to query
+#' @param vertices The vertices to query
+#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead.
 #' @inheritParams neighbors
 #' @inheritParams rlang::args_dots_empty
 #' @return A list of edge sequences.
@@ -877,9 +911,10 @@ adjacent_vertices <- function(
 #' incident_edges(g, c(1, 34))
 incident_edges <- function(
   graph,
-  v,
+  vertices,
   ...,
-  mode = c("out", "in", "all", "total")
+  mode = c("out", "in", "all", "total"),
+  v = deprecated()
 ) {
   # BEGIN GENERATED ARG_HANDLE: incident_edges, do not edit, see tools/generate-migrations.R
   # fmt: skip
@@ -908,17 +943,32 @@ incident_edges <- function(
         "3.0.0",
         what = base::I("Calling `incident_edges()` with positional or abbreviated arguments"),
         details = base::c(
-          i = base::paste0("Detected call:  incident_edges(", base::paste(base::c("graph", "v", .arg_names), collapse = ", "), ")"),
-          i = base::paste0("Use instead:    incident_edges(", base::paste(base::c("graph", "v", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
+          i = base::paste0("Detected call:  incident_edges(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"),
+          i = base::paste0("Use instead:    incident_edges(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
         )
       )
     }
   }
   # END GENERATED ARG_HANDLE
 
+  if (lifecycle::is_present(v)) {
+    if (!missing(vertices)) {
+      cli::cli_abort(c(
+        "Argument {.arg vertices} of {.fn incident_edges} was supplied more than once.",
+        i = "It was also supplied via its legacy name {.arg v}."
+      ))
+    }
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      "incident_edges(v = )",
+      "incident_edges(vertices = )"
+    )
+    vertices <- v
+  }
+
   ensure_igraph(graph)
 
-  vv <- as_igraph_vs(graph, v) - 1
+  vv <- as_igraph_vs(graph, vertices) - 1
   mode <- switch(match.arg(mode), "out" = 1, "in" = 2, "all" = 3, "total" = 3)
 
   on.exit(.Call(Rx_igraph_finalizer))

R/scan.R

@@ -287,7 +287,12 @@ local_scan <- function(
         ## General
       } else {
         sapply(V(graph.us), function(x) {
-          vei <- neighborhood(graph.us, order = k, nodes = x, mode = mode)[[1]]
+          vei <- neighborhood(
+            graph.us,
+            order = k,
+            vertices = x,
+            mode = mode
+          )[[1]]
           if (!is.function(FUN)) {
             FUN <- getFunction(FUN, where = environment())
           }