From 7954b20c89b94c9018e482ed857555bbcea4c535 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 19:12:46 +0000 Subject: [PATCH] refactor: Rename vertex-selector arguments to `vertices` (#2788, #692) The subset selectors `v`, `vids` and `nodes` unify on `vertices` across 24 functions, implementing the #692 scheme: `vertices` selects a subset, `n` counts (previous PR), and single-vertex arguments keep `v` (`neighbors()`, `incident()`, `subcomponent()`). Head selectors keep positional calls working and recover named legacy spellings via surviving sentinel formals; tail selectors ride the registry recovery. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01RTPj4qNv2FWui6etixZeuR --- R/centrality.R | 286 ++++++++++----- R/cocitation.R | 67 +++- R/cohesive.blocks.R | 2 +- R/efficiency.R | 35 +- R/indexing.R | 4 +- R/interface.R | 82 ++++- R/scan.R | 7 +- R/similarity.R | 47 ++- R/structural-properties.R | 347 +++++++++++++----- R/topology.R | 26 +- R/triangles.R | 30 +- man/adjacent.triangles.Rd | 4 +- man/adjacent_vertices.Rd | 12 +- man/alpha.centrality.Rd | 4 +- man/alpha_centrality.Rd | 9 +- man/betweenness.Rd | 13 +- man/bonpow.Rd | 3 +- man/closeness.Rd | 11 +- man/cocitation.Rd | 18 +- man/constraint.Rd | 6 +- man/count_triangles.Rd | 8 +- man/degree.Rd | 16 +- man/delete.vertices.Rd | 2 +- man/delete_vertices.Rd | 6 +- man/distances.Rd | 16 +- man/diversity.Rd | 4 +- man/ego.Rd | 34 +- man/estimate_closeness.Rd | 3 +- man/global_efficiency.Rd | 9 +- man/graph.diversity.Rd | 4 +- man/graph.knn.Rd | 5 +- man/graph.neighborhood.Rd | 3 +- man/graph.strength.Rd | 3 +- man/harmonic_centrality.Rd | 13 +- man/incident_edges.Rd | 12 +- man/induced.subgraph.Rd | 3 +- man/isomorphism_class.Rd | 8 +- man/knn.Rd | 11 +- man/neighborhood.size.Rd | 3 +- man/page.rank.Rd | 4 +- man/page_rank.Rd | 4 +- man/power_centrality.Rd | 13 +- man/shortest.paths.Rd | 3 +- man/similarity.Rd | 11 +- man/similarity.dice.Rd | 3 +- man/similarity.invlogweighted.Rd | 3 +- man/similarity.jaccard.Rd | 3 +- man/strength.Rd | 9 +- man/subgraph.Rd | 11 +- man/transitivity.Rd | 12 +- tests/testthat/_snaps/centrality.md | 9 + .../testthat/_snaps/structural-properties.md | 18 + tests/testthat/test-centrality.R | 71 +++- tests/testthat/test-constant-defaults.R | 22 +- tests/testthat/test-efficiency.R | 2 +- tests/testthat/test-interface.R | 25 +- tests/testthat/test-iterators.R | 2 +- tests/testthat/test-similarity.R | 2 +- tests/testthat/test-structural-properties.R | 93 ++++- tools/migrations/centrality.R | 38 +- tools/migrations/interface.R | 10 +- tools/migrations/similarity-efficiency.R | 10 +- tools/migrations/structural-properties.R | 44 ++- vignettes/igraph.Rmd | 4 +- vignettes/igraph_ES.rmd | 4 +- 65 files changed, 1125 insertions(+), 481 deletions(-) diff --git a/R/centrality.R b/R/centrality.R index 1851503a30b..9db1f2a84aa 100644 --- a/R/centrality.R +++ b/R/centrality.R @@ -28,6 +28,8 @@ subgraph.centrality <- function(graph, diag = FALSE) { #' @inheritParams page_rank #' @param algo `r lifecycle::badge("deprecated")` Use `algorithm` in #' [page_rank()] instead. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` in +#' [page_rank()] instead. #' @keywords internal #' @export page.rank <- function( @@ -45,7 +47,7 @@ page.rank <- function( page_rank( graph = graph, algorithm = algo, - vids = vids, + vertices = vids, directed = directed, damping = damping, personalized = personalized, @@ -113,7 +115,7 @@ graph.strength <- function( lifecycle::deprecate_warn("2.0.0", "graph.strength()", "strength()") strength( graph = graph, - vids = vids, + vertices = vids, mode = mode, loops = loops, weights = weights @@ -161,12 +163,14 @@ graph.eigen <- function( #' `graph.diversity()` was renamed to [diversity()] to create a more #' consistent API. #' @inheritParams diversity +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` in +#' [diversity()] instead. #' @keywords internal #' @export graph.diversity <- function(graph, weights = NULL, vids = V(graph)) { # nocov start lifecycle::deprecate_warn("2.0.0", "graph.diversity()", "diversity()") - diversity(graph = graph, weights = weights, vids = vids) + diversity(graph = graph, weights = weights, vertices = vids) } # nocov end #' Find Eigenvector Centrality Scores of Network Positions @@ -250,7 +254,7 @@ bonpow <- function( lifecycle::deprecate_warn("2.0.0", "bonpow()", "power_centrality()") power_centrality( graph = graph, - nodes = nodes, + vertices = nodes, loops = loops, exponent = exponent, normalized = rescale, @@ -283,7 +287,7 @@ alpha.centrality <- function( lifecycle::deprecate_warn("2.0.0", "alpha.centrality()", "alpha_centrality()") alpha_centrality( graph = graph, - nodes = nodes, + vertices = nodes, alpha = alpha, loops = loops, exo = exo, @@ -340,7 +344,7 @@ estimate_betweenness <- function( betweenness( graph, - v = vids, + vertices = vids, directed = directed, cutoff = cutoff, weights = weights @@ -385,8 +389,9 @@ betweenness.estimate <- estimate_betweenness #' @aliases betweenness.estimate #' @aliases edge.betweenness.estimate #' @param graph The graph to analyze. -#' @param v The vertices for which the vertex betweenness will be calculated. -#' The default `NULL` selects all vertices. +#' @param vertices The vertices for which the vertex betweenness will be +#' calculated. The default `NULL` selects all vertices. +#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether directed paths should be considered while #' determining the shortest paths. @@ -408,7 +413,7 @@ betweenness.estimate <- estimate_betweenness #' @param cutoff The maximum shortest path length to consider when calculating #' betweenness. If negative, then there is no such limit. #' @return A numeric vector with the betweenness score for each vertex in -#' `v` for `betweenness()`. +#' `vertices` for `betweenness()`. #' #' A numeric vector with the edge betweenness score for each edge in `e` #' for `edge_betweenness()`. @@ -435,12 +440,13 @@ betweenness.estimate <- estimate_betweenness #' betweenness <- function( graph, - v = NULL, + vertices = NULL, ..., directed = TRUE, weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + v = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: betweenness, do not edit, see tools/generate-migrations.R # fmt: skip @@ -475,21 +481,36 @@ betweenness <- function( "3.0.0", what = base::I("Calling `betweenness()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: betweenness(", base::paste(base::c("graph", "v", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: betweenness(", base::paste(base::c("graph", "v", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: betweenness(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: betweenness(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE - if (is.null(v)) { - v <- V(graph) + if (lifecycle::is_present(v)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn betweenness} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg v}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "betweenness(v = )", + "betweenness(vertices = )" + ) + vertices <- v + } + + if (is.null(vertices)) { + vertices <- V(graph) } res <- betweenness_cutoff_impl( graph = graph, - vids = v, + vids = vertices, directed = directed, weights = weights, cutoff = cutoff @@ -632,8 +653,9 @@ edge.betweenness.estimate <- estimate_edge_betweenness #' #' @aliases closeness.estimate #' @param graph The graph to analyze. -#' @param vids The vertices for which closeness will be calculated. +#' @param vertices The vertices for which closeness will be calculated. #' The default `NULL` selects all vertices. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param mode Character string, defined the types of the paths used for #' measuring the distance in directed graphs. \dQuote{in} measures the paths @@ -651,7 +673,7 @@ edge.betweenness.estimate <- estimate_edge_betweenness #' @param cutoff The maximum path length to consider when calculating the #' closeness. If zero or negative then there is no such limit. #' @return Numeric vector with the closeness values of all the vertices in -#' `v`. +#' `vertices`. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Freeman, L.C. (1979). Centrality in Social Networks I: #' Conceptual Clarification. *Social Networks*, 1, 215-239. @@ -669,16 +691,19 @@ edge.betweenness.estimate <- estimate_edge_betweenness #' closeness <- function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("out", "in", "all", "total"), weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + vids = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: closeness, 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 closeness}.", i = "Spell out the full argument name.")) # Pre-3.0.0 signature: closeness(graph, vids, mode, weights, normalized, cutoff) .old_signature <- function(mode, weights, normalized, cutoff, ...) { if (...length() > 0L) { @@ -709,21 +734,36 @@ closeness <- function( "3.0.0", what = base::I("Calling `closeness()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: closeness(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: closeness(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: closeness(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: closeness(", 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 closeness} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "closeness(vids = )", + "closeness(vertices = )" + ) + vertices <- vids + } + + if (is.null(vertices)) { + vertices <- V(graph) } closeness_cutoff_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode, weights = weights, normalized = normalized, @@ -1517,8 +1557,9 @@ eigen_centrality <- function( #' #' #' @param graph The input graph. -#' @param vids The vertices for which the strength will be calculated. +#' @param vertices The vertices for which the strength will be calculated. #' The default `NULL` selects all vertices. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param mode Character string, \dQuote{out} for out-degree, \dQuote{in} for #' in-degree or \dQuote{all} for the sum of the two. For undirected graphs this @@ -1551,15 +1592,18 @@ eigen_centrality <- function( #' @export strength <- function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = TRUE, - weights = NULL + weights = NULL, + vids = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: strength, 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 strength}.", i = "Spell out the full argument name.")) # Pre-3.0.0 signature: strength(graph, vids, mode, loops, weights) .old_signature <- function(mode, loops, weights, ...) { if (...length() > 0L) { @@ -1588,21 +1632,36 @@ strength <- function( "3.0.0", what = base::I("Calling `strength()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: strength(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: strength(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: strength(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: strength(", 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 strength} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "strength(vids = )", + "strength(vertices = )" + ) + vertices <- vids + } + + if (is.null(vertices)) { + vertices <- V(graph) } strength_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode, loops = loops, weights = weights @@ -1632,7 +1691,7 @@ strength <- function( #' @param weights `NULL`, or the vector of edge weights to use for the #' computation. If `NULL`, then the \sQuote{weight} attibute is used. Note #' that this measure is not defined for unweighted graphs. -#' @param vids The vertex IDs for which to calculate the measure. +#' @param vertices The vertex IDs for which to calculate the measure. #' The default `NULL` selects all vertices. #' @return A numeric vector, its length is the number of vertices. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -1656,11 +1715,13 @@ diversity <- function( graph, ..., weights = NULL, - vids = NULL + vertices = NULL ) { # BEGIN GENERATED ARG_HANDLE: diversity, do not edit, see tools/generate-migrations.R # fmt: skip if (...length() > 0L) { + .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("v")) + if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn diversity}.") # Pre-3.0.0 signature: diversity(graph, weights, vids) .old_signature <- function(weights, vids, ...) { if (...length() > 0L) { @@ -1671,7 +1732,7 @@ diversity <- function( } base::c( if (!base::missing(weights)) base::list(weights = weights), - if (!base::missing(vids)) base::list(vids = vids) + if (!base::missing(vids)) base::list(vertices = vids) ) } .arg_handle <- .old_signature(...) @@ -1679,7 +1740,7 @@ diversity <- function( .arg_names <- base::names(.arg_handle) .arg_conflict <- base::intersect(.arg_names, base::c( if (!base::missing(weights)) "weights", - if (!base::missing(vids)) "vids" + if (!base::missing(vertices)) "vertices" )) if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn diversity} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}.")) base::list2env(.arg_handle, base::environment()) @@ -1687,7 +1748,7 @@ diversity <- function( "3.0.0", what = base::I("Calling `diversity()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: diversity(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"), + i = base::paste0("Detected call: diversity(", base::paste(base::c("graph", base::c(weights = "weights", vertices = "vids")[.arg_names]), collapse = ", "), ")"), i = base::paste0("Use instead: diversity(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) @@ -1695,14 +1756,14 @@ diversity <- function( } # END GENERATED ARG_HANDLE - if (is.null(vids)) { - vids <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } diversity_impl( graph = graph, weights = weights, - vids = vids + vids = vertices ) } @@ -1913,7 +1974,7 @@ hub_score <- function( #' for all but small graphs. `"arpack"` uses the ARPACK library, the #' default implementation from igraph version 0.5 until version 0.7. It computes #' PageRank scores by solving an eingevalue problem. -#' @param vids The vertices of interest. +#' @param vertices The vertices of interest. #' The default `NULL` selects all vertices. #' @param directed Logical, if true directed paths will be considered for #' directed graphs. It is ignored for undirected graphs. @@ -1975,7 +2036,7 @@ page_rank <- function( graph, ..., algorithm = c("prpack", "arpack"), - vids = NULL, + vertices = NULL, directed = TRUE, damping = 0.85, personalized = NULL, @@ -1985,7 +2046,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("a", "al", "alg", "d")) + .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("a", "al", "alg", "v", "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, ...) { @@ -1997,7 +2058,7 @@ page_rank <- function( } base::c( if (!base::missing(algo)) base::list(algorithm = algo), - if (!base::missing(vids)) base::list(vids = vids), + if (!base::missing(vids)) base::list(vertices = vids), if (!base::missing(directed)) base::list(directed = directed), if (!base::missing(damping)) base::list(damping = damping), if (!base::missing(personalized)) base::list(personalized = personalized), @@ -2010,7 +2071,7 @@ page_rank <- function( .arg_names <- base::names(.arg_handle) .arg_conflict <- base::intersect(.arg_names, base::c( if (!base::missing(algorithm)) "algorithm", - if (!base::missing(vids)) "vids", + if (!base::missing(vertices)) "vertices", if (!base::missing(directed)) "directed", if (!base::missing(damping)) "damping", if (!base::missing(personalized)) "personalized", @@ -2023,7 +2084,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", base::c(algorithm = "algo", vids = "vids", directed = "directed", damping = "damping", personalized = "personalized", weights = "weights", options = "options")[.arg_names]), collapse = ", "), ")"), + i = base::paste0("Detected call: page_rank(", base::paste(base::c("graph", base::c(algorithm = "algo", vertices = "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 = ", "), ")") ) ) @@ -2031,14 +2092,14 @@ page_rank <- function( } # END GENERATED ARG_HANDLE - if (is.null(vids)) { - vids <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } personalized_pagerank_impl( graph = graph, algo = algorithm, - vids = vids, + vids = vertices, directed = directed, damping = damping, personalized = personalized, @@ -2058,8 +2119,9 @@ page_rank <- function( #' default), then the function calculates the exact harmonic centrality scores. #' #' @param graph The graph to analyze. -#' @param vids The vertices for which harmonic centrality will be calculated. -#' The default `NULL` selects all vertices. +#' @param vertices The vertices for which harmonic centrality will be +#' calculated. The default `NULL` selects all vertices. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param mode Character string, defining the types of the paths used for #' measuring the distance in directed graphs. \dQuote{out} follows paths along @@ -2078,7 +2140,7 @@ page_rank <- function( #' harmonic centrality. There is no such limit when the cutoff is negative. Note that #' zero cutoff means that only paths of at most length 0 are considered. #' @return Numeric vector with the harmonic centrality scores of all the vertices in -#' `v`. +#' `vertices`. #' @seealso [betweenness()], [closeness()] #' @references M. Marchiori and V. Latora, Harmony in the small-world, #' *Physica A* 285, pp. 539-546 (2000). @@ -2096,16 +2158,19 @@ page_rank <- function( #' harmonic_centrality <- function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("out", "in", "all", "total"), weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + vids = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: harmonic_centrality, 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 harmonic_centrality}.", i = "Spell out the full argument name.")) # Pre-3.0.0 signature: harmonic_centrality(graph, vids, mode, weights, normalized, cutoff) .old_signature <- function(mode, weights, normalized, cutoff, ...) { if (...length() > 0L) { @@ -2136,21 +2201,36 @@ harmonic_centrality <- function( "3.0.0", what = base::I("Calling `harmonic_centrality()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: harmonic_centrality(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: harmonic_centrality(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: harmonic_centrality(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: harmonic_centrality(", 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 harmonic_centrality} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "harmonic_centrality(vids = )", + "harmonic_centrality(vertices = )" + ) + vertices <- vids + } + + if (is.null(vertices)) { + vertices <- V(graph) } harmonic_centrality_cutoff_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode, weights = weights, normalized = normalized, @@ -2226,7 +2306,7 @@ bonpow.sparse <- function( #' Find Bonacich Power Centrality Scores of Network Positions #' #' `power_centrality()` takes a graph (`dat`) and returns the Boncich power -#' centralities of positions (selected by `nodes`). The decay rate for +#' centralities of positions (selected by `vertices`). The decay rate for #' power contributions is specified by `exponent` (1 by default). #' #' Bonacich's power centrality measure is defined by @@ -2277,8 +2357,9 @@ bonpow.sparse <- function( #' is important to think about the edge direction and what it represents. #' #' @param graph the input graph. -#' @param nodes vertex sequence indicating which vertices are to be included in -#' the calculation. The default `NULL` selects all vertices. +#' @param vertices vertex sequence indicating which vertices are to be included +#' in the calculation. The default `NULL` selects all vertices. +#' @param nodes `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param loops Logical indicating whether or not the diagonal should be #' treated as valid data. Set this true if and only if the data can contain @@ -2340,20 +2421,21 @@ bonpow.sparse <- function( #' power_centrality <- function( graph, - nodes = NULL, + vertices = NULL, ..., loops = FALSE, exponent = 1, normalized = FALSE, tol = 1e-7, sparse = TRUE, - weights = NULL + weights = NULL, + nodes = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: power_centrality, do not edit, see tools/generate-migrations.R # fmt: skip if (...length() > 0L) { - .arg_forbidden <- base::intersect(base::names(base::sys.call()), base::c("n", "no")) - if (base::length(.arg_forbidden) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_forbidden)}} matches multiple formal arguments of {.fn power_centrality}.", i = "Spell out the full argument name.")) + .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("n", "no")) + if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn power_centrality}.") # Pre-3.0.0 signature: power_centrality(graph, nodes, loops, exponent, rescale, tol, sparse, weights) .old_signature <- function(loops, exponent, rescale, tol, sparse, weights, ...) { if (...length() > 0L) { @@ -2388,23 +2470,38 @@ power_centrality <- function( "3.0.0", what = base::I("Calling `power_centrality()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: power_centrality(", base::paste(base::c("graph", "nodes", base::c(loops = "loops", exponent = "exponent", normalized = "rescale", tol = "tol", sparse = "sparse", weights = "weights")[.arg_names]), collapse = ", "), ")"), - i = base::paste0("Use instead: power_centrality(", base::paste(base::c("graph", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: power_centrality(", base::paste(base::c("graph", "vertices", base::c(loops = "loops", exponent = "exponent", normalized = "rescale", tol = "tol", sparse = "sparse", weights = "weights")[.arg_names]), collapse = ", "), ")"), + i = base::paste0("Use instead: power_centrality(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE - if (is.null(nodes)) { - nodes <- V(graph) + if (lifecycle::is_present(nodes)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn power_centrality} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg nodes}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "power_centrality(nodes = )", + "power_centrality(vertices = )" + ) + vertices <- nodes + } + + if (is.null(vertices)) { + vertices <- V(graph) } - nodes <- as_igraph_vs(graph, nodes) + vertices <- as_igraph_vs(graph, vertices) if (sparse) { res <- bonpow.sparse( graph, - nodes, + vertices, loops, exponent, normalized, @@ -2414,7 +2511,7 @@ power_centrality <- function( } else { res <- bonpow.dense( graph, - nodes, + vertices, loops, exponent, normalized, @@ -2424,7 +2521,7 @@ power_centrality <- function( } if (igraph_opt("add.vertex.names") && is_named(graph)) { - names(res) <- vertex_attr(graph, "name", nodes) + names(res) <- vertex_attr(graph, "name", vertices) } res @@ -2512,9 +2609,10 @@ alpha.centrality.sparse <- function( #' #' @param graph The input graph, can be directed or undirected. In undirected #' graphs, edges are treated as if they were reciprocal directed ones. -#' @param nodes Vertex sequence, the vertices for which the alpha centrality +#' @param vertices Vertex sequence, the vertices for which the alpha centrality #' values are returned. The default `NULL` selects all vertices. #' (For technical reasons they will be calculated for all vertices, anyway.) +#' @param nodes `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param alpha Parameter specifying the relative importance of endogenous #' versus exogenous factors in the determination of centrality. See details @@ -2555,14 +2653,15 @@ alpha.centrality.sparse <- function( #' alpha_centrality <- function( graph, - nodes = NULL, + vertices = NULL, ..., alpha = 1, loops = FALSE, exo = 1, weights = NULL, tol = 1e-7, - sparse = TRUE + sparse = TRUE, + nodes = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: alpha_centrality, do not edit, see tools/generate-migrations.R # fmt: skip @@ -2601,23 +2700,38 @@ alpha_centrality <- function( "3.0.0", what = base::I("Calling `alpha_centrality()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: alpha_centrality(", base::paste(base::c("graph", "nodes", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: alpha_centrality(", base::paste(base::c("graph", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: alpha_centrality(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: alpha_centrality(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE - if (is.null(nodes)) { - nodes <- V(graph) + if (lifecycle::is_present(nodes)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn alpha_centrality} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg nodes}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "alpha_centrality(nodes = )", + "alpha_centrality(vertices = )" + ) + vertices <- nodes + } + + if (is.null(vertices)) { + vertices <- V(graph) } - nodes <- as_igraph_vs(graph, nodes) + vertices <- as_igraph_vs(graph, vertices) if (sparse) { res <- alpha.centrality.sparse( graph, - nodes, + vertices, alpha, loops, exo, @@ -2627,7 +2741,7 @@ alpha_centrality <- function( } else { res <- alpha.centrality.dense( graph, - nodes, + vertices, alpha, loops, exo, @@ -2636,7 +2750,7 @@ alpha_centrality <- function( ) } if (igraph_opt("add.vertex.names") && is_named(graph)) { - names(res) <- vertex_attr(graph, "name", nodes) + names(res) <- vertex_attr(graph, "name", vertices) } res } diff --git a/R/cocitation.R b/R/cocitation.R index f5c67ab2774..ff5e012d935 100644 --- a/R/cocitation.R +++ b/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,18 +54,33 @@ #' 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 @@ -72,18 +88,33 @@ cocitation <- function(graph, v = NULL) { #' @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 diff --git a/R/cohesive.blocks.R b/R/cohesive.blocks.R index 18eef59d2ef..f75f842da72 100644 --- a/R/cohesive.blocks.R +++ b/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) { diff --git a/R/efficiency.R b/R/efficiency.R index c572f7f3aa8..7d015fa3180 100644 --- a/R/efficiency.R +++ b/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 diff --git a/R/indexing.R b/R/indexing.R index 1f61e246621..2135d3b9666 100644 --- a/R/indexing.R +++ b/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]))) diff --git a/R/interface.R b/R/interface.R index 59ce5d4178e..09fcbaab1f8 100644 --- a/R/interface.R +++ b/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)) diff --git a/R/scan.R b/R/scan.R index a719650c8d1..e39b84c7e64 100644 --- a/R/scan.R +++ b/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()) } diff --git a/R/similarity.R b/R/similarity.R index 1b4b2313b15..98743a323ef 100644 --- a/R/similarity.R +++ b/R/similarity.R @@ -26,8 +26,9 @@ #' 25(3):211-230, 2003. #' #' @param graph The input graph. -#' @param vids The vertex IDs for which the similarity is calculated. The +#' @param vertices The vertex IDs for which the similarity is calculated. The #' default `NULL` selects all vertices. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param mode The type of neighboring vertices to use for the calculation, #' possible values: \sQuote{`out`}, \sQuote{`in`}, @@ -35,7 +36,7 @@ #' @param loops Whether to include vertices themselves in the neighbor #' sets. #' @param method The method to use. -#' @return A `length(vids)` by `length(vids)` numeric matrix +#' @return A `length(vertices)` by `length(vertices)` numeric matrix #' containing the similarity scores. This argument is ignored by the #' `invlogweighted` method. #' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi @@ -53,7 +54,7 @@ #' similarity(g, method = "jaccard") similarity <- function( graph, - vids = NULL, + vertices = NULL, ..., mode = c( "all", @@ -66,11 +67,14 @@ similarity <- function( "jaccard", "dice", "invlogweighted" - ) + ), + vids = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: similarity, 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 similarity}.", i = "Spell out the full argument name.")) .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("m")) if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn similarity}.") # Pre-3.0.0 signature: similarity(graph, vids, mode, loops, method) @@ -101,37 +105,52 @@ similarity <- function( "3.0.0", what = base::I("Calling `similarity()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: similarity(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: similarity(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: similarity(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: similarity(", 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 similarity} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "similarity(vids = )", + "similarity(vertices = )" + ) + vertices <- vids + } + + if (is.null(vertices)) { + vertices <- V(graph) } method <- igraph_match_arg(method) if (method == "jaccard") { similarity_jaccard_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode, loops = loops ) } else if (method == "dice") { similarity_dice_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode, loops = loops ) } else if (method == "invlogweighted") { similarity_inverse_log_weighted_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode ) } @@ -161,7 +180,7 @@ similarity.jaccard <- function( similarity( graph = graph, - vids = vids, + vertices = vids, mode = mode, loops = loops, method = "jaccard" @@ -192,7 +211,7 @@ similarity.dice <- function( similarity( graph = graph, - vids = vids, + vertices = vids, mode = mode, loops = loops, method = "dice" @@ -222,7 +241,7 @@ similarity.invlogweighted <- function( similarity( graph = graph, - vids = vids, + vertices = vids, mode = mode, method = "invlogweighted" ) diff --git a/R/structural-properties.R b/R/structural-properties.R index 7790956ce80..d762068bbdc 100644 --- a/R/structural-properties.R +++ b/R/structural-properties.R @@ -154,7 +154,7 @@ shortest.paths <- function( mode <- igraph_match_arg(mode) distances( graph = graph, - v = v, + vertices = v, to = to, mode = mode, weights = weights, @@ -184,7 +184,7 @@ neighborhood.size <- function( ego_size( graph = graph, order = order, - nodes = nodes, + vertices = nodes, mode = mode, mindist = mindist ) @@ -337,7 +337,7 @@ induced.subgraph <- function( ) { # nocov start lifecycle::deprecate_warn("2.0.0", "induced.subgraph()", "induced_subgraph()") - induced_subgraph(graph = graph, vids = vids, impl = impl) + induced_subgraph(graph = graph, vertices = vids, impl = impl) } # nocov end #' Find the multiple or loop edges in a graph @@ -378,7 +378,7 @@ graph.neighborhood <- function( make_ego_graph( graph = graph, order = order, - nodes = nodes, + vertices = nodes, mode = mode, mindist = mindist ) @@ -431,7 +431,7 @@ graph.knn <- function( lifecycle::deprecate_warn("2.0.0", "graph.knn()", "knn()") knn( graph = graph, - vids = vids, + vertices = vids, mode = mode, neighbor.degree.mode = neighbor.degree.mode, weights = weights @@ -1038,8 +1038,9 @@ mean_distance <- function( #' #' #' @param graph The graph to analyze. -#' @param v The IDs of vertices of which the degree will be calculated. +#' @param vertices The IDs of vertices of which the degree will be calculated. #' The default `NULL` selects all vertices. +#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @param mode Character string, \dQuote{out} for out-degree, \dQuote{in} for #' in-degree or \dQuote{total} for the sum of the two. For undirected graphs #' this argument is ignored. \dQuote{all} is a synonym of \dQuote{total}. @@ -1049,7 +1050,7 @@ mean_distance <- function( #' number of vertices in the graph. #' @inheritParams rlang::args_dots_empty #' @return For `degree()` a numeric vector of the same length as argument -#' `v`. +#' `vertices`. #' #' For `degree_distribution()` a numeric vector of the same length as the #' maximum degree plus one. The first element is the relative frequency zero @@ -1077,11 +1078,12 @@ mean_distance <- function( #' degree <- function( graph, - v = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = TRUE, - normalized = FALSE + normalized = FALSE, + v = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: degree, do not edit, see tools/generate-migrations.R # fmt: skip @@ -1114,24 +1116,35 @@ degree <- function( "3.0.0", what = base::I("Calling `degree()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: degree(", base::paste(base::c("graph", "v", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: degree(", base::paste(base::c("graph", "v", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: degree(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: degree(", 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 degree} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg v}." + )) + } + lifecycle::deprecate_soft("3.0.0", "degree(v = )", "degree(vertices = )") + vertices <- v + } + ensure_igraph(graph) - if (is.null(v)) { - v <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } - v <- as_igraph_vs(graph, v) + vertices <- as_igraph_vs(graph, vertices) mode <- igraph_match_arg(mode) res <- degree_impl( graph = graph, - vids = v, + vids = vertices, mode = mode, loops = loops ) @@ -1140,7 +1153,7 @@ degree <- function( res <- res / (vcount(graph) - 1) } if (igraph_opt("add.vertex.names") && is_named(graph)) { - names(res) <- V(graph)$name[v] + names(res) <- V(graph)$name[vertices] } res } @@ -1150,17 +1163,33 @@ degree <- function( max_degree <- function( graph, ..., - v = NULL, + vertices = NULL, mode = c("all", "out", "in", "total"), - loops = TRUE + loops = TRUE, + v = deprecated() ) { - if (is.null(v)) { - v <- V(graph) + if (lifecycle::is_present(v)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn max_degree} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg v}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "max_degree(v = )", + "max_degree(vertices = )" + ) + vertices <- v + } + + if (is.null(vertices)) { + vertices <- V(graph) } maxdegree_impl( graph = graph, - v = v, + v = vertices, mode = mode, loops = loops ) @@ -1294,8 +1323,9 @@ degree_distribution <- function(graph, cumulative = FALSE, ...) { #' histogram. #' #' @param graph The graph to work on. -#' @param v Numeric vector, the vertices from which the shortest paths will be -#' calculated. The default `NULL` selects all vertices. +#' @param vertices Numeric vector, the vertices from which the shortest paths +#' will be calculated. The default `NULL` selects all vertices. +#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @param to Numeric vector, the vertices to which the shortest paths will be #' calculated. The default `NULL` includes all vertices. Note that for #' `distances()` every vertex must be included here at most once. (This @@ -1332,8 +1362,9 @@ degree_distribution <- function(graph, cumulative = FALSE, ...) { #' FALSE, the length of the missing paths are considered as having infinite #' length, making the mean distance infinite as well. #' @return For `distances()` a numeric matrix with `length(to)` -#' columns and `length(v)` rows. The shortest path length from a vertex to -#' itself is always zero. For unreachable vertices `Inf` is included. +#' columns and `length(vertices)` rows. The shortest path length from a +#' vertex to itself is always zero. For unreachable vertices `Inf` is +#' included. #' #' For `shortest_paths()` a named list with four entries is returned: #' \item{vpath}{This itself is a list, of length `length(to)`; list @@ -1440,7 +1471,7 @@ degree_distribution <- function(graph, cumulative = FALSE, ...) { #' distances <- function( graph, - v = NULL, + vertices = NULL, to = NULL, ..., mode = c("all", "out", "in"), @@ -1452,7 +1483,8 @@ distances <- function( "bellman-ford", "johnson", "floyd-warshall" - ) + ), + v = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: distances, do not edit, see tools/generate-migrations.R # fmt: skip @@ -1485,17 +1517,32 @@ distances <- function( "3.0.0", what = base::I("Calling `distances()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: distances(", base::paste(base::c("graph", "v", "to", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: distances(", base::paste(base::c("graph", "v", "to", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: distances(", base::paste(base::c("graph", "vertices", "to", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: distances(", base::paste(base::c("graph", "vertices", "to", 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 distances} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg v}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "distances(v = )", + "distances(vertices = )" + ) + vertices <- v + } + ensure_igraph(graph) - if (is.null(v)) { - v <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } if (is.null(to)) { to <- V(graph) @@ -1508,7 +1555,7 @@ distances <- function( mode <- "out" } - v <- as_igraph_vs(graph, v) + vertices <- as_igraph_vs(graph, vertices) to <- as_igraph_vs(graph, to) mode <- igraph_match_arg(mode) mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3) @@ -1544,7 +1591,7 @@ distances <- function( res <- .Call( Rx_igraph_shortest_paths, graph, - v - 1, + vertices - 1, to - 1, as.numeric(mode), weights, @@ -1552,7 +1599,7 @@ distances <- function( ) if (igraph_opt("add.vertex.names") && is_named(graph)) { - rownames(res) <- V(graph)$name[v] + rownames(res) <- V(graph)$name[vertices] colnames(res) <- V(graph)$name[to] } res @@ -2006,8 +2053,9 @@ subgraph <- function(graph, vids) { } #' @rdname subgraph -#' @param vids Numeric vector, the vertices of the original graph which will -#' form the subgraph. +#' @param vertices Numeric vector, the vertices of the original graph which +#' will form the subgraph. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param impl Character scalar, to choose between two implementation of the #' subgraph calculation. \sQuote{`copy_and_delete`} copies the graph @@ -2020,13 +2068,16 @@ subgraph <- function(graph, vids) { #' @export induced_subgraph <- function( graph, - vids, + vertices, ..., - impl = c("auto", "copy_and_delete", "create_from_scratch") + impl = c("auto", "copy_and_delete", "create_from_scratch"), + vids = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: induced_subgraph, 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 induced_subgraph}.", i = "Spell out the full argument name.")) # Pre-3.0.0 signature: induced_subgraph(graph, vids, impl) .old_signature <- function(impl, ...) { if (...length() > 0L) { @@ -2051,23 +2102,38 @@ induced_subgraph <- function( "3.0.0", what = base::I("Calling `induced_subgraph()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: induced_subgraph(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: induced_subgraph(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: induced_subgraph(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: induced_subgraph(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE + if (lifecycle::is_present(vids)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn induced_subgraph} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "induced_subgraph(vids = )", + "induced_subgraph(vertices = )" + ) + vertices <- vids + } + # Argument checks ensure_igraph(graph) - vids <- as_igraph_vs(graph, vids) + vertices <- as_igraph_vs(graph, vertices) impl <- igraph_match_arg(impl) # Function call res <- induced_subgraph_impl( graph = graph, - vids = vids, + vids = vertices, impl = impl ) @@ -2199,7 +2265,7 @@ subgraph.edges <- function(graph, eids, delete.vertices = TRUE) { #' } #' \item{"local"}{ #' The local transitivity of an undirected graph. -#' It is calculated for each vertex given in the `vids` argument. +#' It is calculated for each vertex given in the `vertices` argument. #' The local transitivity of a vertex is the ratio of the count of triangles connected to the vertex #' and the triples centered on the vertex. #' In directed graphs, edge directions are ignored. @@ -2221,7 +2287,7 @@ subgraph.edges <- function(graph, eids, delete.vertices = TRUE) { #' } #' } #' @inheritParams rlang::args_dots_empty -#' @param vids The vertex IDs for the local transitivity will be calculated. +#' @param vertices The vertex IDs for the local transitivity will be calculated. #' This will be ignored for global transitivity types. The default value is #' `NULL`, in this case all vertices are considered. It is slightly faster #' to supply `NULL` here than `V(graph)`. @@ -2243,7 +2309,7 @@ subgraph.edges <- function(graph, eids, delete.vertices = TRUE) { #' are no connected triples in the graph. #' #' For \sQuote{`local`} a vector of transitivity scores, one for each -#' vertex in \sQuote{`vids`}. +#' vertex in \sQuote{`vertices`}. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @references Wasserman, S., and Faust, K. (1994). *Social Network #' Analysis: Methods and Applications.* Cambridge: Cambridge University Press. @@ -2265,8 +2331,8 @@ subgraph.edges <- function(graph, eids, delete.vertices = TRUE) { #' gw <- graph_from_literal(A - B:C:D:E, B - C:D, C - D) #' E(gw)$weight <- 1 #' E(gw)[V(gw)[name == "A"] %--% V(gw)[name == "E"]]$weight <- 5 -#' transitivity(gw, vids = "A", type = "local") -#' transitivity(gw, vids = "A", type = "weighted") +#' transitivity(gw, vertices = "A", type = "local") +#' transitivity(gw, vertices = "A", type = "weighted") #' #' # Weighted reduces to "local" if weights are the same #' gw2 <- sample_gnp(1000, 10 / 1000) @@ -2291,13 +2357,15 @@ transitivity <- function( "weighted" ), ..., - vids = NULL, + vertices = NULL, weights = NULL, isolates = c("NaN", "zero") ) { # BEGIN GENERATED ARG_HANDLE: transitivity, do not edit, see tools/generate-migrations.R # fmt: skip if (...length() > 0L) { + .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("v")) + if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn transitivity}.") # Pre-3.0.0 signature: transitivity(graph, type, vids, weights, isolates) .old_signature <- function(vids, weights, isolates, ...) { if (...length() > 0L) { @@ -2307,7 +2375,7 @@ transitivity <- function( cli::cli_abort(base::c("Unexpected argument passed to {.fn transitivity}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame()) } base::c( - if (!base::missing(vids)) base::list(vids = vids), + if (!base::missing(vids)) base::list(vertices = vids), if (!base::missing(weights)) base::list(weights = weights), if (!base::missing(isolates)) base::list(isolates = isolates) ) @@ -2316,7 +2384,7 @@ transitivity <- function( if (base::length(.arg_handle) > 0L) { .arg_names <- base::names(.arg_handle) .arg_conflict <- base::intersect(.arg_names, base::c( - if (!base::missing(vids)) "vids", + if (!base::missing(vertices)) "vertices", if (!base::missing(weights)) "weights", if (!base::missing(isolates)) "isolates" )) @@ -2326,7 +2394,7 @@ transitivity <- function( "3.0.0", what = base::I("Calling `transitivity()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: transitivity(", base::paste(base::c("graph", "type", .arg_names), collapse = ", "), ")"), + i = base::paste0("Detected call: transitivity(", base::paste(base::c("graph", "type", base::c(vertices = "vids", weights = "weights", isolates = "isolates")[.arg_names]), collapse = ", "), ")"), i = base::paste0("Use instead: transitivity(", base::paste(base::c("graph", "type", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) @@ -2368,7 +2436,7 @@ transitivity <- function( ) } else if (type == 1) { isolates_num <- as.double(switch(isolates, "nan" = 0, "zero" = 1)) - if (is.null(vids)) { + if (is.null(vertices)) { res <- .Call( Rx_igraph_transitivity_local_undirected_all, graph, @@ -2381,11 +2449,11 @@ transitivity <- function( } else { res <- transitivity_local_undirected_impl( graph = graph, - vids = vids, + vids = vertices, mode = isolates ) if (igraph_opt("add.vertex.names") && is_named(graph)) { - vids_indices <- as_igraph_vs(graph, vids) + vids_indices <- as_igraph_vs(graph, vertices) names(res) <- V(graph)$name[vids_indices] } res @@ -2396,11 +2464,11 @@ transitivity <- function( mode = isolates ) } else if (type == 3) { - # Save original vids for naming if needed - vids_for_names <- if (is.null(vids)) V(graph) else vids + # Save original vertices for naming if needed + vids_for_names <- if (is.null(vertices)) V(graph) else vertices res <- if (is.null(weights)) { - if (is.null(vids)) { + if (is.null(vertices)) { transitivity_local_undirected_impl( graph = graph, mode = isolates @@ -2408,12 +2476,12 @@ transitivity <- function( } else { transitivity_local_undirected_impl( graph = graph, - vids = vids, + vids = vertices, mode = isolates ) } } else { - if (is.null(vids)) { + if (is.null(vertices)) { transitivity_barrat_impl( graph = graph, weights = weights, @@ -2422,7 +2490,7 @@ transitivity <- function( } else { transitivity_barrat_impl( graph = graph, - vids = vids, + vids = vertices, weights = weights, mode = isolates ) @@ -2461,8 +2529,9 @@ transitivity <- function( #' graph adjacency matrix. For isolated vertices, constraint is undefined. #' #' @param graph A graph object, the input graph. -#' @param nodes The vertices for which the constraint will be calculated. +#' @param vertices The vertices for which the constraint will be calculated. #' The default `NULL` selects all vertices. +#' @param nodes `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param weights The weights of the edges. If this is `NULL` and there is #' a `weight` edge attribute this is used. If there is no such edge @@ -2483,9 +2552,10 @@ transitivity <- function( #' constraint <- function( graph, - nodes = NULL, + vertices = NULL, ..., - weights = NULL + weights = NULL, + nodes = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: constraint, do not edit, see tools/generate-migrations.R # fmt: skip @@ -2514,19 +2584,34 @@ constraint <- function( "3.0.0", what = base::I("Calling `constraint()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: constraint(", base::paste(base::c("graph", "nodes", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: constraint(", base::paste(base::c("graph", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: constraint(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: constraint(", base::paste(base::c("graph", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE + if (lifecycle::is_present(nodes)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn constraint} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg nodes}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "constraint(nodes = )", + "constraint(vertices = )" + ) + vertices <- nodes + } + ensure_igraph(graph) - if (is.null(nodes)) { - nodes <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } - nodes <- as_igraph_vs(graph, nodes) + vertices <- as_igraph_vs(graph, vertices) if (is.null(weights)) { if ("weight" %in% edge_attr_names(graph)) { @@ -2536,11 +2621,11 @@ constraint <- function( res <- constraint_impl( graph = graph, - vids = nodes, + vids = vertices, weights = weights ) if (igraph_opt("add.vertex.names") && is_named(graph)) { - names(res) <- V(graph)$name[nodes] + names(res) <- V(graph)$name[vertices] } res } @@ -2721,10 +2806,11 @@ edge_density <- function( ego_size <- function( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: ego_size, do not edit, see tools/generate-migrations.R # fmt: skip @@ -2757,17 +2843,32 @@ ego_size <- function( "3.0.0", what = base::I("Calling `ego_size()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: ego_size(", base::paste(base::c("graph", "order", "nodes", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: ego_size(", base::paste(base::c("graph", "order", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: ego_size(", base::paste(base::c("graph", "order", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: ego_size(", base::paste(base::c("graph", "order", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE + if (lifecycle::is_present(nodes)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn ego_size} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg nodes}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "ego_size(nodes = )", + "ego_size(vertices = )" + ) + vertices <- nodes + } + ensure_igraph(graph) - if (is.null(nodes)) { - nodes <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } mode <- igraph_match_arg(mode) mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3) @@ -2777,7 +2878,7 @@ ego_size <- function( .Call( Rx_igraph_neighborhood_size, graph, - as_igraph_vs(graph, nodes) - 1, + as_igraph_vs(graph, vertices) - 1, as.numeric(order), as.numeric(mode), mindist @@ -2820,8 +2921,9 @@ neighborhood_size <- ego_size #' @param graph The input graph. #' @param order Integer giving the order of the neighborhood. Negative values #' indicate an infinite order. -#' @param nodes The vertices for which the calculation is performed. +#' @param vertices The vertices for which the calculation is performed. #' The default `NULL` selects all vertices. +#' @param nodes `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param mode Character constant, it specifies how to use the direction of #' the edges if a directed graph is analyzed. For \sQuote{out} only the @@ -2880,10 +2982,11 @@ neighborhood_size <- ego_size ego <- function( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: ego, do not edit, see tools/generate-migrations.R # fmt: skip @@ -2916,17 +3019,28 @@ ego <- function( "3.0.0", what = base::I("Calling `ego()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: ego(", base::paste(base::c("graph", "order", "nodes", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: ego(", base::paste(base::c("graph", "order", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: ego(", base::paste(base::c("graph", "order", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: ego(", base::paste(base::c("graph", "order", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE + if (lifecycle::is_present(nodes)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn ego} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg nodes}." + )) + } + lifecycle::deprecate_soft("3.0.0", "ego(nodes = )", "ego(vertices = )") + vertices <- nodes + } + ensure_igraph(graph) - if (is.null(nodes)) { - nodes <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } mode <- igraph_match_arg(mode) mode <- switch(mode, "out" = 1, "in" = 2, "all" = 3) @@ -2936,7 +3050,7 @@ ego <- function( res <- .Call( Rx_igraph_neighborhood, graph, - as_igraph_vs(graph, nodes) - 1, + as_igraph_vs(graph, vertices) - 1, as.numeric(order), as.numeric(mode), mindist @@ -2959,10 +3073,11 @@ neighborhood <- ego make_ego_graph <- function( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: make_ego_graph, do not edit, see tools/generate-migrations.R # fmt: skip @@ -2995,17 +3110,32 @@ make_ego_graph <- function( "3.0.0", what = base::I("Calling `make_ego_graph()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: make_ego_graph(", base::paste(base::c("graph", "order", "nodes", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: make_ego_graph(", base::paste(base::c("graph", "order", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: make_ego_graph(", base::paste(base::c("graph", "order", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: make_ego_graph(", base::paste(base::c("graph", "order", "vertices", base::paste0(.arg_names, " = ")), collapse = ", "), ")") ) ) } } # END GENERATED ARG_HANDLE + if (lifecycle::is_present(nodes)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn make_ego_graph} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg nodes}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "make_ego_graph(nodes = )", + "make_ego_graph(vertices = )" + ) + vertices <- nodes + } + ensure_igraph(graph) - if (is.null(nodes)) { - nodes <- V(graph) + if (is.null(vertices)) { + vertices <- V(graph) } mode <- igraph_match_arg(mode) mode <- switch(mode, "out" = 1L, "in" = 2L, "all" = 3L) @@ -3015,7 +3145,7 @@ make_ego_graph <- function( res <- .Call( Rx_igraph_neighborhood_graphs, graph, - as_igraph_vs(graph, nodes) - 1, + as_igraph_vs(graph, vertices) - 1, as.numeric(order), as.integer(mode), mindist @@ -4898,10 +5028,11 @@ which_mutual <- function( #' and \eqn{k_v}{k_v} is the neighbors' degree, specified by `neighbor_degree_mode`. #' #' @param graph The input graph. It may be directed. -#' @param vids The vertices for which the calculation is performed. +#' @param vertices The vertices for which the calculation is performed. #' The default `NULL` includes all vertices. Note, that if not all vertices are given here, then #' both \sQuote{`knn`} and \sQuote{`knnk`} will be calculated based #' on the given vertices only. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @inheritParams rlang::args_dots_empty #' @param mode Character constant to indicate the type of neighbors to consider #' in directed graphs. `out` considers out-neighbors, `in` considers @@ -4919,7 +5050,7 @@ which_mutual <- function( #' @return A list with two members: #' \describe{ #' \item{knn}{ -#' A numeric vector giving the average nearest neighbor degree for all vertices in `vids`. +#' A numeric vector giving the average nearest neighbor degree for all vertices in `vertices`. #' } #' \item{knnk}{ #' A numeric vector, its length is the maximum (total) vertex degree in the graph. @@ -4955,15 +5086,18 @@ which_mutual <- function( #' @export knn <- function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), neighbor.degree.mode = c("all", "out", "in", "total"), - weights = NULL + weights = NULL, + vids = deprecated() ) { # BEGIN GENERATED ARG_HANDLE: knn, 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 knn}.", i = "Spell out the full argument name.")) # Pre-3.0.0 signature: knn(graph, vids, mode, neighbor.degree.mode, weights) .old_signature <- function(mode, neighbor.degree.mode, weights, ...) { if (...length() > 0L) { @@ -4992,21 +5126,32 @@ knn <- function( "3.0.0", what = base::I("Calling `knn()` with positional or abbreviated arguments"), details = base::c( - i = base::paste0("Detected call: knn(", base::paste(base::c("graph", "vids", .arg_names), collapse = ", "), ")"), - i = base::paste0("Use instead: knn(", base::paste(base::c("graph", "vids", base::paste0(.arg_names, " = ")), collapse = ", "), ")") + i = base::paste0("Detected call: knn(", base::paste(base::c("graph", "vertices", .arg_names), collapse = ", "), ")"), + i = base::paste0("Use instead: knn(", 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 knn} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft("3.0.0", "knn(vids = )", "knn(vertices = )") + vertices <- vids + } + + if (is.null(vertices)) { + vertices <- V(graph) } avg_nearest_neighbor_degree_impl( graph = graph, - vids = vids, + vids = vertices, mode = mode, neighbor_degree_mode = neighbor.degree.mode, weights = weights diff --git a/R/topology.R b/R/topology.R index 1069c076de5..c1a7f802b6e 100644 --- a/R/topology.R +++ b/R/topology.R @@ -1251,8 +1251,9 @@ subgraph_isomorphisms <- function( #' vertices and undirected graphs with 3 to 6 vertices. #' #' @param graph The input graph. -#' @param v Optionally a vertex sequence. If not missing, then an induced -#' subgraph of the input graph, consisting of this vertices, is used. +#' @param vertices Optionally a vertex sequence. If not missing, then an +#' induced subgraph of the input graph, consisting of this vertices, is used. +#' @param v `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @return An integer number. #' #' @aliases graph.isoclass graph.isoclass.subgraph @@ -1266,11 +1267,26 @@ subgraph_isomorphisms <- function( #' isomorphism_class(g1) #' isomorphism_class(g2) #' isomorphic(g1, g2) -isomorphism_class <- function(graph, v) { - if (missing(v)) { +isomorphism_class <- function(graph, vertices, v = deprecated()) { + if (lifecycle::is_present(v)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn isomorphism_class} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg v}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "isomorphism_class(v = )", + "isomorphism_class(vertices = )" + ) + vertices <- v + } + + if (missing(vertices)) { graph.isoclass(graph) } else { - graph.isoclass.subgraph(graph, v) + graph.isoclass.subgraph(graph, vertices) } } diff --git a/R/triangles.R b/R/triangles.R index 5a0e5ebb9d9..d4dcf18a788 100644 --- a/R/triangles.R +++ b/R/triangles.R @@ -15,7 +15,7 @@ adjacent.triangles <- function(graph, vids = V(graph)) { "adjacent.triangles()", "count_triangles()" ) - count_triangles(graph = graph, vids = vids) + count_triangles(graph = graph, vertices = vids) } # nocov end ## ----------------------------------------------------------------------- @@ -55,9 +55,10 @@ adjacent.triangles <- function(graph, vids = V(graph)) { #' @aliases triangles #' @param graph The input graph. It might be directed, but edge directions are #' ignored. -#' @param vids The vertices to query. This might be a vector of numeric IDs, -#' or a character vector of symbolic vertex names for named graphs. The +#' @param vertices The vertices to query. This might be a vector of numeric +#' IDs, or a character vector of symbolic vertex names for named graphs. The #' default `NULL` selects all vertices. +#' @param vids `r lifecycle::badge("deprecated")` Use `vertices` instead. #' @return For `triangles()` a numeric vector of vertex IDs, the first three #' vertices belong to the first triangle found, etc. #' @@ -96,13 +97,28 @@ triangles <- function(graph) { #' @export #' @rdname count_triangles -count_triangles <- function(graph, vids = NULL) { - if (is.null(vids)) { - vids <- V(graph) +count_triangles <- function(graph, vertices = NULL, vids = deprecated()) { + if (lifecycle::is_present(vids)) { + if (!missing(vertices)) { + cli::cli_abort(c( + "Argument {.arg vertices} of {.fn count_triangles} was supplied more than once.", + i = "It was also supplied via its legacy name {.arg vids}." + )) + } + lifecycle::deprecate_soft( + "3.0.0", + "count_triangles(vids = )", + "count_triangles(vertices = )" + ) + vertices <- vids + } + + if (is.null(vertices)) { + vertices <- V(graph) } count_adjacent_triangles_impl( graph = graph, - vids = vids + vids = vertices ) } diff --git a/man/adjacent.triangles.Rd b/man/adjacent.triangles.Rd index 88abc2cda05..a111c0a6a01 100644 --- a/man/adjacent.triangles.Rd +++ b/man/adjacent.triangles.Rd @@ -10,9 +10,7 @@ adjacent.triangles(graph, vids = V(graph)) \item{graph}{The input graph. It might be directed, but edge directions are ignored.} -\item{vids}{The vertices to query. This might be a vector of numeric IDs, -or a character vector of symbolic vertex names for named graphs. The -default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} diff --git a/man/adjacent_vertices.Rd b/man/adjacent_vertices.Rd index 7cd09d74caa..9afaa6c1cad 100644 --- a/man/adjacent_vertices.Rd +++ b/man/adjacent_vertices.Rd @@ -4,18 +4,26 @@ \alias{adjacent_vertices} \title{Adjacent vertices of multiple vertices in a graph} \usage{ -adjacent_vertices(graph, v, ..., mode = c("out", "in", "all", "total")) +adjacent_vertices( + graph, + vertices, + ..., + mode = c("out", "in", "all", "total"), + v = deprecated() +) } \arguments{ \item{graph}{Input graph.} -\item{v}{The vertices to query.} +\item{vertices}{The vertices to query.} \item{...}{These dots are for future extensions and must be empty.} \item{mode}{Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). This is ignored for undirected graphs.} + +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A list of vertex sequences. diff --git a/man/alpha.centrality.Rd b/man/alpha.centrality.Rd index 70234ba4973..dc84e3bff94 100644 --- a/man/alpha.centrality.Rd +++ b/man/alpha.centrality.Rd @@ -19,9 +19,7 @@ alpha.centrality( \item{graph}{The input graph, can be directed or undirected. In undirected graphs, edges are treated as if they were reciprocal directed ones.} -\item{nodes}{Vertex sequence, the vertices for which the alpha centrality -values are returned. The default \code{NULL} selects all vertices. -(For technical reasons they will be calculated for all vertices, anyway.)} +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{alpha}{Parameter specifying the relative importance of endogenous versus exogenous factors in the determination of centrality. See details diff --git a/man/alpha_centrality.Rd b/man/alpha_centrality.Rd index 55b20f96d20..3374ecd4f09 100644 --- a/man/alpha_centrality.Rd +++ b/man/alpha_centrality.Rd @@ -6,21 +6,22 @@ \usage{ alpha_centrality( graph, - nodes = NULL, + vertices = NULL, ..., alpha = 1, loops = FALSE, exo = 1, weights = NULL, tol = 1e-07, - sparse = TRUE + sparse = TRUE, + nodes = deprecated() ) } \arguments{ \item{graph}{The input graph, can be directed or undirected. In undirected graphs, edges are treated as if they were reciprocal directed ones.} -\item{nodes}{Vertex sequence, the vertices for which the alpha centrality +\item{vertices}{Vertex sequence, the vertices for which the alpha centrality values are returned. The default \code{NULL} selects all vertices. (For technical reasons they will be calculated for all vertices, anyway.)} @@ -57,6 +58,8 @@ is included in the matrix.} \item{sparse}{Logical, whether to use sparse matrices for the calculation. The \sQuote{Matrix} package is required for sparse matrix support} + +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A numeric vector contaning the centrality scores for the selected diff --git a/man/betweenness.Rd b/man/betweenness.Rd index f8dbd6d4a34..c0a9ef99791 100644 --- a/man/betweenness.Rd +++ b/man/betweenness.Rd @@ -9,12 +9,13 @@ \usage{ betweenness( graph, - v = NULL, + vertices = NULL, ..., directed = TRUE, weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + v = deprecated() ) edge_betweenness( @@ -29,8 +30,8 @@ edge_betweenness( \arguments{ \item{graph}{The graph to analyze.} -\item{v}{The vertices for which the vertex betweenness will be calculated. -The default \code{NULL} selects all vertices.} +\item{vertices}{The vertices for which the vertex betweenness will be +calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -57,12 +58,14 @@ from each other may be less than \eqn{(n-1)(n-2)/2}.} \item{cutoff}{The maximum shortest path length to consider when calculating betweenness. If negative, then there is no such limit.} +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} + \item{e}{The edges for which the edge betweenness will be calculated. The default \code{NULL} selects all edges.} } \value{ A numeric vector with the betweenness score for each vertex in -\code{v} for \code{betweenness()}. +\code{vertices} for \code{betweenness()}. A numeric vector with the edge betweenness score for each edge in \code{e} for \code{edge_betweenness()}. diff --git a/man/bonpow.Rd b/man/bonpow.Rd index 338399252dc..4e1f690aeb5 100644 --- a/man/bonpow.Rd +++ b/man/bonpow.Rd @@ -17,8 +17,7 @@ bonpow( \arguments{ \item{graph}{the input graph.} -\item{nodes}{vertex sequence indicating which vertices are to be included in -the calculation. The default \code{NULL} selects all vertices.} +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{loops}{Logical indicating whether or not the diagonal should be treated as valid data. Set this true if and only if the data can contain diff --git a/man/closeness.Rd b/man/closeness.Rd index 3103521ed9b..3eea243c009 100644 --- a/man/closeness.Rd +++ b/man/closeness.Rd @@ -7,18 +7,19 @@ \usage{ closeness( graph, - vids = NULL, + vertices = NULL, ..., mode = c("out", "in", "all", "total"), weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + vids = deprecated() ) } \arguments{ \item{graph}{The graph to analyze.} -\item{vids}{The vertices for which closeness will be calculated. +\item{vertices}{The vertices for which closeness will be calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -41,10 +42,12 @@ all reachable vertices.} \item{cutoff}{The maximum path length to consider when calculating the closeness. If zero or negative then there is no such limit.} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ Numeric vector with the closeness values of all the vertices in -\code{v}. +\code{vertices}. } \description{ Closeness centrality measures how many steps are required to access every other diff --git a/man/cocitation.Rd b/man/cocitation.Rd index e148aecbf82..2a264ec9dc4 100644 --- a/man/cocitation.Rd +++ b/man/cocitation.Rd @@ -5,21 +5,23 @@ \alias{bibcoupling} \title{Cocitation coupling} \usage{ -cocitation(graph, v = NULL) +cocitation(graph, vertices = NULL, v = deprecated()) -bibcoupling(graph, v = NULL) +bibcoupling(graph, vertices = NULL, v = deprecated()) } \arguments{ \item{graph}{The graph object to analyze} -\item{v}{Vertex sequence or numeric vector, the vertex IDs for which the -cocitation or bibliographic coupling values we want to calculate. The +\item{vertices}{Vertex sequence or numeric vector, the vertex IDs for which +the cocitation or bibliographic coupling values we want to calculate. The default \code{NULL} selects all vertices.} + +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ -A numeric matrix with \code{length(v)} lines and +A numeric matrix with \code{length(vertices)} lines and \code{vcount(graph)} columns. Element \verb{(i,j)} contains the cocitation -or bibliographic coupling for vertices \code{v[i]} and \code{j}. +or bibliographic coupling for vertices \code{vertices[i]} and \code{j}. } \description{ Two vertices are cocited if there is another vertex citing both of them. @@ -29,10 +31,10 @@ both cite, \code{bibcoupling()} calculates this. } \details{ \code{cocitation()} calculates the cocitation counts for the vertices in the -\code{v} argument and all vertices in the graph. +\code{vertices} argument and all vertices in the graph. \code{bibcoupling()} calculates the bibliographic coupling for vertices in -\code{v} and all vertices in the graph. +\code{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 diff --git a/man/constraint.Rd b/man/constraint.Rd index 3dd16200b38..f8b148eee1e 100644 --- a/man/constraint.Rd +++ b/man/constraint.Rd @@ -4,12 +4,12 @@ \alias{constraint} \title{Burt's constraint} \usage{ -constraint(graph, nodes = NULL, ..., weights = NULL) +constraint(graph, vertices = NULL, ..., weights = NULL, nodes = deprecated()) } \arguments{ \item{graph}{A graph object, the input graph.} -\item{nodes}{The vertices for which the constraint will be calculated. +\item{vertices}{The vertices for which the constraint will be calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -17,6 +17,8 @@ The default \code{NULL} selects all vertices.} \item{weights}{The weights of the edges. If this is \code{NULL} and there is a \code{weight} edge attribute this is used. If there is no such edge attribute all edges will have the same weight.} + +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A numeric vector of constraint scores diff --git a/man/count_triangles.Rd b/man/count_triangles.Rd index 99af82f07da..071823cac23 100644 --- a/man/count_triangles.Rd +++ b/man/count_triangles.Rd @@ -7,15 +7,17 @@ \usage{ triangles(graph) -count_triangles(graph, vids = NULL) +count_triangles(graph, vertices = NULL, vids = deprecated()) } \arguments{ \item{graph}{The input graph. It might be directed, but edge directions are ignored.} -\item{vids}{The vertices to query. This might be a vector of numeric IDs, -or a character vector of symbolic vertex names for named graphs. The +\item{vertices}{The vertices to query. This might be a vector of numeric +IDs, or a character vector of symbolic vertex names for named graphs. The default \code{NULL} selects all vertices.} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ For \code{triangles()} a numeric vector of vertex IDs, the first three diff --git a/man/degree.Rd b/man/degree.Rd index ec7c9277b44..2ea46e2c9f9 100644 --- a/man/degree.Rd +++ b/man/degree.Rd @@ -9,19 +9,21 @@ \usage{ degree( graph, - v = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = TRUE, - normalized = FALSE + normalized = FALSE, + v = deprecated() ) max_degree( graph, ..., - v = NULL, + vertices = NULL, mode = c("all", "out", "in", "total"), - loops = TRUE + loops = TRUE, + v = deprecated() ) mean_degree(graph, ..., loops = TRUE) @@ -31,7 +33,7 @@ degree_distribution(graph, cumulative = FALSE, ...) \arguments{ \item{graph}{The graph to analyze.} -\item{v}{The IDs of vertices of which the degree will be calculated. +\item{vertices}{The IDs of vertices of which the degree will be calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -46,12 +48,14 @@ this argument is ignored. \dQuote{all} is a synonym of \dQuote{total}.} \code{TRUE} then the result is divided by \eqn{n-1}, where \eqn{n} is the number of vertices in the graph.} +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} + \item{cumulative}{Logical; whether the cumulative degree distribution is to be calculated.} } \value{ For \code{degree()} a numeric vector of the same length as argument -\code{v}. +\code{vertices}. For \code{degree_distribution()} a numeric vector of the same length as the maximum degree plus one. The first element is the relative frequency zero diff --git a/man/delete.vertices.Rd b/man/delete.vertices.Rd index a956f6e4657..6da08a31b46 100644 --- a/man/delete.vertices.Rd +++ b/man/delete.vertices.Rd @@ -9,7 +9,7 @@ delete.vertices(graph, v) \arguments{ \item{graph}{The input graph.} -\item{v}{The vertices to remove, a vertex sequence.} +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} diff --git a/man/delete_vertices.Rd b/man/delete_vertices.Rd index 5703eb9e502..8aac339c655 100644 --- a/man/delete_vertices.Rd +++ b/man/delete_vertices.Rd @@ -4,12 +4,14 @@ \alias{delete_vertices} \title{Delete vertices from a graph} \usage{ -delete_vertices(graph, v) +delete_vertices(graph, vertices, v = deprecated()) } \arguments{ \item{graph}{The input graph.} -\item{v}{The vertices to remove, a vertex sequence.} +\item{vertices}{The vertices to remove, a vertex sequence.} + +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ The graph, with the vertices removed. diff --git a/man/distances.Rd b/man/distances.Rd index 2e84b17143a..abeb683a349 100644 --- a/man/distances.Rd +++ b/man/distances.Rd @@ -21,13 +21,14 @@ mean_distance( distances( graph, - v = NULL, + vertices = NULL, to = NULL, ..., mode = c("all", "out", "in"), weights = NULL, algorithm = c("automatic", "unweighted", "dijkstra", "bellman-ford", "johnson", - "floyd-warshall") + "floyd-warshall"), + v = deprecated() ) shortest_paths( @@ -77,8 +78,8 @@ Functions accepting this argument (like \code{mean_distance()}) return additional information like the number of disconnected vertex pairs in the result when this parameter is set to \code{TRUE}.} -\item{v}{Numeric vector, the vertices from which the shortest paths will be -calculated. The default \code{NULL} selects all vertices.} +\item{vertices}{Numeric vector, the vertices from which the shortest paths +will be calculated. The default \code{NULL} selects all vertices.} \item{to}{Numeric vector, the vertices to which the shortest paths will be calculated. The default \code{NULL} includes all vertices. Note that for @@ -103,6 +104,8 @@ that the igraph C core might still override your choice in obvious cases, i.e. if there are no edge weights, then the unweighted algorithm will be used, regardless of this argument.} +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} + \item{from}{Numeric constant, the vertex from or to the shortest paths will be calculated. Note that right now this is not a vector of vertex IDs, but only a single vertex.} @@ -130,8 +133,9 @@ are reached.} } \value{ For \code{distances()} a numeric matrix with \code{length(to)} -columns and \code{length(v)} rows. The shortest path length from a vertex to -itself is always zero. For unreachable vertices \code{Inf} is included. +columns and \code{length(vertices)} rows. The shortest path length from a +vertex to itself is always zero. For unreachable vertices \code{Inf} is +included. For \code{shortest_paths()} a named list with four entries is returned: \item{vpath}{This itself is a list, of length \code{length(to)}; list diff --git a/man/diversity.Rd b/man/diversity.Rd index 0fe5d21dfd4..a2663c07308 100644 --- a/man/diversity.Rd +++ b/man/diversity.Rd @@ -4,7 +4,7 @@ \alias{diversity} \title{Graph diversity} \usage{ -diversity(graph, ..., weights = NULL, vids = NULL) +diversity(graph, ..., weights = NULL, vertices = NULL) } \arguments{ \item{graph}{The input graph. Edge directions are ignored.} @@ -15,7 +15,7 @@ diversity(graph, ..., weights = NULL, vids = NULL) computation. If \code{NULL}, then the \sQuote{weight} attibute is used. Note that this measure is not defined for unweighted graphs.} -\item{vids}{The vertex IDs for which to calculate the measure. +\item{vertices}{The vertex IDs for which to calculate the measure. The default \code{NULL} selects all vertices.} } \value{ diff --git a/man/ego.Rd b/man/ego.Rd index 67ddfceda02..dbff6b1e0c0 100644 --- a/man/ego.Rd +++ b/man/ego.Rd @@ -16,55 +16,61 @@ connect(graph, order, ..., mode = c("all", "out", "in", "total")) ego_size( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) neighborhood_size( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) ego( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) neighborhood( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) make_ego_graph( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) make_neighborhood_graph( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) } \arguments{ @@ -83,10 +89,12 @@ vertices from which the source vertex is reachable in at most \code{order} steps are counted. \sQuote{"all"} ignores the direction of the edges. This argument is ignored for undirected graphs.} -\item{nodes}{The vertices for which the calculation is performed. +\item{vertices}{The vertices for which the calculation is performed. The default \code{NULL} selects all vertices.} \item{mindist}{The minimum distance to include the vertex in the result.} + +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ \itemize{ diff --git a/man/estimate_closeness.Rd b/man/estimate_closeness.Rd index 2b7d031524d..7b823331419 100644 --- a/man/estimate_closeness.Rd +++ b/man/estimate_closeness.Rd @@ -16,8 +16,7 @@ estimate_closeness( \arguments{ \item{graph}{The graph to analyze.} -\item{vids}{The vertices for which closeness will be calculated. -The default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{Character string, defined the types of the paths used for measuring the distance in directed graphs. \dQuote{in} measures the paths diff --git a/man/global_efficiency.Rd b/man/global_efficiency.Rd index 2a390554fa2..d007fe8edc4 100644 --- a/man/global_efficiency.Rd +++ b/man/global_efficiency.Rd @@ -10,11 +10,12 @@ global_efficiency(graph, ..., weights = NULL, directed = TRUE) local_efficiency( graph, - vids = NULL, + vertices = NULL, ..., weights = NULL, directed = TRUE, - mode = c("all", "out", "in", "total") + mode = c("all", "out", "in", "total"), + vids = deprecated() ) average_local_efficiency( @@ -37,13 +38,15 @@ and the graph has a \code{weight} edge attribute, then it is used automatically. \item{directed}{Logical, whether to consider directed paths. Ignored for undirected graphs.} -\item{vids}{The vertex IDs of the vertices for which the calculation will be done. +\item{vertices}{The vertex IDs of the vertices for which the calculation will be done. Applies to the local efficiency calculation only. The default \code{NULL} selects all vertices.} \item{mode}{Specifies how to define the local neighborhood of a vertex in directed graphs. \dQuote{out} considers out-neighbors only, \dQuote{in} considers in-neighbors only, \dQuote{all} considers both.} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ For \code{global_efficiency()}, the global efficiency of the graph as a diff --git a/man/graph.diversity.Rd b/man/graph.diversity.Rd index bd1ca92af59..ba558ee3f9e 100644 --- a/man/graph.diversity.Rd +++ b/man/graph.diversity.Rd @@ -13,8 +13,8 @@ graph.diversity(graph, weights = NULL, vids = V(graph)) computation. If \code{NULL}, then the \sQuote{weight} attibute is used. Note that this measure is not defined for unweighted graphs.} -\item{vids}{The vertex IDs for which to calculate the measure. -The default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} in +\code{\link[=diversity]{diversity()}} instead.} } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} diff --git a/man/graph.knn.Rd b/man/graph.knn.Rd index 70c502f64e1..739826451e3 100644 --- a/man/graph.knn.Rd +++ b/man/graph.knn.Rd @@ -15,10 +15,7 @@ graph.knn( \arguments{ \item{graph}{The input graph. It may be directed.} -\item{vids}{The vertices for which the calculation is performed. -The default \code{NULL} includes all vertices. Note, that if not all vertices are given here, then -both \sQuote{\code{knn}} and \sQuote{\code{knnk}} will be calculated based -on the given vertices only.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{Character constant to indicate the type of neighbors to consider in directed graphs. \code{out} considers out-neighbors, \verb{in} considers diff --git a/man/graph.neighborhood.Rd b/man/graph.neighborhood.Rd index 2ed769672d3..1c9c159e636 100644 --- a/man/graph.neighborhood.Rd +++ b/man/graph.neighborhood.Rd @@ -18,8 +18,7 @@ graph.neighborhood( \item{order}{Integer giving the order of the neighborhood. Negative values indicate an infinite order.} -\item{nodes}{The vertices for which the calculation is performed. -The default \code{NULL} selects all vertices.} +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. For \sQuote{out} only the diff --git a/man/graph.strength.Rd b/man/graph.strength.Rd index daf41c663fa..0904fc8214b 100644 --- a/man/graph.strength.Rd +++ b/man/graph.strength.Rd @@ -15,8 +15,7 @@ graph.strength( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertices for which the strength will be calculated. -The default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{Character string, \dQuote{out} for out-degree, \dQuote{in} for in-degree or \dQuote{all} for the sum of the two. For undirected graphs this diff --git a/man/harmonic_centrality.Rd b/man/harmonic_centrality.Rd index 1c93bc61cac..fca01107a7d 100644 --- a/man/harmonic_centrality.Rd +++ b/man/harmonic_centrality.Rd @@ -6,19 +6,20 @@ \usage{ harmonic_centrality( graph, - vids = NULL, + vertices = NULL, ..., mode = c("out", "in", "all", "total"), weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + vids = deprecated() ) } \arguments{ \item{graph}{The graph to analyze.} -\item{vids}{The vertices for which harmonic centrality will be calculated. -The default \code{NULL} selects all vertices.} +\item{vertices}{The vertices for which harmonic centrality will be +calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -41,10 +42,12 @@ If false, the result is the sum of inverse path lengths to other vertices.} \item{cutoff}{The maximum path length to consider when calculating the harmonic centrality. There is no such limit when the cutoff is negative. Note that zero cutoff means that only paths of at most length 0 are considered.} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ Numeric vector with the harmonic centrality scores of all the vertices in -\code{v}. +\code{vertices}. } \description{ The harmonic centrality of a vertex is the mean inverse distance to all other diff --git a/man/incident_edges.Rd b/man/incident_edges.Rd index 325ae62623c..359a2b288d5 100644 --- a/man/incident_edges.Rd +++ b/man/incident_edges.Rd @@ -4,18 +4,26 @@ \alias{incident_edges} \title{Incident edges of multiple vertices in a graph} \usage{ -incident_edges(graph, v, ..., mode = c("out", "in", "all", "total")) +incident_edges( + graph, + vertices, + ..., + mode = c("out", "in", "all", "total"), + v = deprecated() +) } \arguments{ \item{graph}{Input graph.} -\item{v}{The vertices to query} +\item{vertices}{The vertices to query} \item{...}{These dots are for future extensions and must be empty.} \item{mode}{Whether to query outgoing (\sQuote{out}), incoming (\sQuote{in}) edges, or both types (\sQuote{all}). This is ignored for undirected graphs.} + +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A list of edge sequences. diff --git a/man/induced.subgraph.Rd b/man/induced.subgraph.Rd index 78e14f9f85c..9df044903c7 100644 --- a/man/induced.subgraph.Rd +++ b/man/induced.subgraph.Rd @@ -13,8 +13,7 @@ induced.subgraph( \arguments{ \item{graph}{The original graph.} -\item{vids}{Numeric vector, the vertices of the original graph which will -form the subgraph.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{impl}{Character scalar, to choose between two implementation of the subgraph calculation. \sQuote{\code{copy_and_delete}} copies the graph diff --git a/man/isomorphism_class.Rd b/man/isomorphism_class.Rd index 86bc8544fa3..0501bd10dc8 100644 --- a/man/isomorphism_class.Rd +++ b/man/isomorphism_class.Rd @@ -6,13 +6,15 @@ \alias{graph.isoclass.subgraph} \title{Isomorphism class of a graph} \usage{ -isomorphism_class(graph, v) +isomorphism_class(graph, vertices, v = deprecated()) } \arguments{ \item{graph}{The input graph.} -\item{v}{Optionally a vertex sequence. If not missing, then an induced -subgraph of the input graph, consisting of this vertices, is used.} +\item{vertices}{Optionally a vertex sequence. If not missing, then an +induced subgraph of the input graph, consisting of this vertices, is used.} + +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ An integer number. diff --git a/man/knn.Rd b/man/knn.Rd index 96ba5158ecf..bcde8cd2b48 100644 --- a/man/knn.Rd +++ b/man/knn.Rd @@ -6,17 +6,18 @@ \usage{ knn( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), neighbor.degree.mode = c("all", "out", "in", "total"), - weights = NULL + weights = NULL, + vids = deprecated() ) } \arguments{ \item{graph}{The input graph. It may be directed.} -\item{vids}{The vertices for which the calculation is performed. +\item{vertices}{The vertices for which the calculation is performed. The default \code{NULL} includes all vertices. Note, that if not all vertices are given here, then both \sQuote{\code{knn}} and \sQuote{\code{knnk}} will be calculated based on the given vertices only.} @@ -38,12 +39,14 @@ degree. But note that \code{knnk} is still given in the function of the normal vertex degree. Weights are are used to calculate a weighted degree (also called \code{\link[=strength]{strength()}}) instead of the degree.} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A list with two members: \describe{ \item{knn}{ -A numeric vector giving the average nearest neighbor degree for all vertices in \code{vids}. +A numeric vector giving the average nearest neighbor degree for all vertices in \code{vertices}. } \item{knnk}{ A numeric vector, its length is the maximum (total) vertex degree in the graph. diff --git a/man/neighborhood.size.Rd b/man/neighborhood.size.Rd index 3264876a6fe..3a2fdbcdc01 100644 --- a/man/neighborhood.size.Rd +++ b/man/neighborhood.size.Rd @@ -18,8 +18,7 @@ neighborhood.size( \item{order}{Integer giving the order of the neighborhood. Negative values indicate an infinite order.} -\item{nodes}{The vertices for which the calculation is performed. -The default \code{NULL} selects all vertices.} +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{Character constant, it specifies how to use the direction of the edges if a directed graph is analyzed. For \sQuote{out} only the diff --git a/man/page.rank.Rd b/man/page.rank.Rd index 41839e26df2..5ffe00dc689 100644 --- a/man/page.rank.Rd +++ b/man/page.rank.Rd @@ -21,8 +21,8 @@ page.rank( \item{algo}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{algorithm} in \code{\link[=page_rank]{page_rank()}} instead.} -\item{vids}{The vertices of interest. -The default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} in +\code{\link[=page_rank]{page_rank()}} instead.} \item{directed}{Logical, if true directed paths will be considered for directed graphs. It is ignored for undirected graphs.} diff --git a/man/page_rank.Rd b/man/page_rank.Rd index c205f129a6b..202b2fc7da8 100644 --- a/man/page_rank.Rd +++ b/man/page_rank.Rd @@ -8,7 +8,7 @@ page_rank( graph, ..., algorithm = c("prpack", "arpack"), - vids = NULL, + vertices = NULL, directed = TRUE, damping = 0.85, personalized = NULL, @@ -30,7 +30,7 @@ for all but small graphs. \code{"arpack"} uses the ARPACK library, the default implementation from igraph version 0.5 until version 0.7. It computes PageRank scores by solving an eingevalue problem.} -\item{vids}{The vertices of interest. +\item{vertices}{The vertices of interest. The default \code{NULL} selects all vertices.} \item{directed}{Logical, if true directed paths will be considered for diff --git a/man/power_centrality.Rd b/man/power_centrality.Rd index 49d80273525..c48246579b4 100644 --- a/man/power_centrality.Rd +++ b/man/power_centrality.Rd @@ -6,21 +6,22 @@ \usage{ power_centrality( graph, - nodes = NULL, + vertices = NULL, ..., loops = FALSE, exponent = 1, normalized = FALSE, tol = 1e-07, sparse = TRUE, - weights = NULL + weights = NULL, + nodes = deprecated() ) } \arguments{ \item{graph}{the input graph.} -\item{nodes}{vertex sequence indicating which vertices are to be included in -the calculation. The default \code{NULL} selects all vertices.} +\item{vertices}{vertex sequence indicating which vertices are to be included +in the calculation. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -53,13 +54,15 @@ used as weights. The attribute must be numeric or logical. } If multiple edges share endpoints, the value of an arbitrarily chosen edge is included in the matrix.} + +\item{nodes}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A vector, containing the centrality scores. } \description{ \code{power_centrality()} takes a graph (\code{dat}) and returns the Boncich power -centralities of positions (selected by \code{nodes}). The decay rate for +centralities of positions (selected by \code{vertices}). The decay rate for power contributions is specified by \code{exponent} (1 by default). } \details{ diff --git a/man/shortest.paths.Rd b/man/shortest.paths.Rd index 041f8de75b4..a1347e4da4b 100644 --- a/man/shortest.paths.Rd +++ b/man/shortest.paths.Rd @@ -16,8 +16,7 @@ shortest.paths( \arguments{ \item{graph}{The graph to work on.} -\item{v}{Numeric vector, the vertices from which the shortest paths will be -calculated. The default \code{NULL} selects all vertices.} +\item{v}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{to}{Numeric vector, the vertices to which the shortest paths will be calculated. The default \code{NULL} includes all vertices. Note that for diff --git a/man/similarity.Rd b/man/similarity.Rd index 505e887ec6d..da7f3fb7a47 100644 --- a/man/similarity.Rd +++ b/man/similarity.Rd @@ -6,17 +6,18 @@ \usage{ similarity( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = FALSE, - method = c("jaccard", "dice", "invlogweighted") + method = c("jaccard", "dice", "invlogweighted"), + vids = deprecated() ) } \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The +\item{vertices}{The vertex IDs for which the similarity is calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -29,9 +30,11 @@ possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, sets.} \item{method}{The method to use.} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ -A \code{length(vids)} by \code{length(vids)} numeric matrix +A \code{length(vertices)} by \code{length(vertices)} numeric matrix containing the similarity scores. This argument is ignored by the \code{invlogweighted} method. } diff --git a/man/similarity.dice.Rd b/man/similarity.dice.Rd index eef1059ad76..7f19c480ca5 100644 --- a/man/similarity.dice.Rd +++ b/man/similarity.dice.Rd @@ -14,8 +14,7 @@ similarity.dice( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{The type of neighboring vertices to use for the calculation, possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, diff --git a/man/similarity.invlogweighted.Rd b/man/similarity.invlogweighted.Rd index 8fbc142be0f..ea618ec1838 100644 --- a/man/similarity.invlogweighted.Rd +++ b/man/similarity.invlogweighted.Rd @@ -13,8 +13,7 @@ similarity.invlogweighted( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{The type of neighboring vertices to use for the calculation, possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, diff --git a/man/similarity.jaccard.Rd b/man/similarity.jaccard.Rd index f28b381f80a..081e73e158c 100644 --- a/man/similarity.jaccard.Rd +++ b/man/similarity.jaccard.Rd @@ -14,8 +14,7 @@ similarity.jaccard( \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertex IDs for which the similarity is calculated. The -default \code{NULL} selects all vertices.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} \item{mode}{The type of neighboring vertices to use for the calculation, possible values: \sQuote{\code{out}}, \sQuote{\verb{in}}, diff --git a/man/strength.Rd b/man/strength.Rd index cf0e0765c59..cf7b2356626 100644 --- a/man/strength.Rd +++ b/man/strength.Rd @@ -6,17 +6,18 @@ \usage{ strength( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = TRUE, - weights = NULL + weights = NULL, + vids = deprecated() ) } \arguments{ \item{graph}{The input graph.} -\item{vids}{The vertices for which the strength will be calculated. +\item{vertices}{The vertices for which the strength will be calculated. The default \code{NULL} selects all vertices.} \item{...}{These dots are for future extensions and must be empty.} @@ -32,6 +33,8 @@ attribute, then this is used by default. If the graph does not have a \code{weight} edge attribute and this argument is \code{NULL}, then a \code{\link[=degree]{degree()}} is called. If this is \code{NA}, then no edge weights are used (even if the graph has a \code{weight} edge attribute).} + +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} } \value{ A numeric vector giving the strength of the vertices. diff --git a/man/subgraph.Rd b/man/subgraph.Rd index fd06736e8e7..3dd9858bb68 100644 --- a/man/subgraph.Rd +++ b/man/subgraph.Rd @@ -10,9 +10,10 @@ subgraph(graph, vids) induced_subgraph( graph, - vids, + vertices, ..., - impl = c("auto", "copy_and_delete", "create_from_scratch") + impl = c("auto", "copy_and_delete", "create_from_scratch"), + vids = deprecated() ) subgraph_from_edges(graph, eids, ..., delete.vertices = TRUE) @@ -20,8 +21,10 @@ subgraph_from_edges(graph, eids, ..., delete.vertices = TRUE) \arguments{ \item{graph}{The original graph.} -\item{vids}{Numeric vector, the vertices of the original graph which will -form the subgraph.} +\item{vids}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{vertices} instead.} + +\item{vertices}{Numeric vector, the vertices of the original graph which +will form the subgraph.} \item{...}{These dots are for future extensions and must be empty.} diff --git a/man/transitivity.Rd b/man/transitivity.Rd index e40240a408c..66c838b76e8 100644 --- a/man/transitivity.Rd +++ b/man/transitivity.Rd @@ -9,7 +9,7 @@ transitivity( type = c("undirected", "global", "globalundirected", "localundirected", "local", "average", "localaverage", "localaverageundirected", "barrat", "weighted"), ..., - vids = NULL, + vertices = NULL, weights = NULL, isolates = c("NaN", "zero") ) @@ -26,7 +26,7 @@ In directed graphs, edge directions are ignored. } \item{"local"}{ The local transitivity of an undirected graph. -It is calculated for each vertex given in the \code{vids} argument. +It is calculated for each vertex given in the \code{vertices} argument. The local transitivity of a vertex is the ratio of the count of triangles connected to the vertex and the triples centered on the vertex. In directed graphs, edge directions are ignored. @@ -50,7 +50,7 @@ The same as \code{barrat}. \item{...}{These dots are for future extensions and must be empty.} -\item{vids}{The vertex IDs for the local transitivity will be calculated. +\item{vertices}{The vertex IDs for the local transitivity will be calculated. This will be ignored for global transitivity types. The default value is \code{NULL}, in this case all vertices are considered. It is slightly faster to supply \code{NULL} here than \code{V(graph)}.} @@ -76,7 +76,7 @@ For \sQuote{\code{global}} a single number, or \code{NaN} if there are no connected triples in the graph. For \sQuote{\code{local}} a vector of transitivity scores, one for each -vertex in \sQuote{\code{vids}}. +vertex in \sQuote{\code{vertices}}. } \description{ Transitivity measures the probability that the adjacent vertices of a vertex @@ -120,8 +120,8 @@ transitivity(g2) # this is about 10/1000 gw <- graph_from_literal(A - B:C:D:E, B - C:D, C - D) E(gw)$weight <- 1 E(gw)[V(gw)[name == "A"] \%--\% V(gw)[name == "E"]]$weight <- 5 -transitivity(gw, vids = "A", type = "local") -transitivity(gw, vids = "A", type = "weighted") +transitivity(gw, vertices = "A", type = "local") +transitivity(gw, vertices = "A", type = "weighted") # Weighted reduces to "local" if weights are the same gw2 <- sample_gnp(1000, 10 / 1000) diff --git a/tests/testthat/_snaps/centrality.md b/tests/testthat/_snaps/centrality.md index ab3d6b88bdc..c937c394aee 100644 --- a/tests/testthat/_snaps/centrality.md +++ b/tests/testthat/_snaps/centrality.md @@ -87,3 +87,12 @@ i Detected call: page_rank(graph, algo) i Use instead: page_rank(graph, algorithm = ) +# closeness(vids = ) is deprecated but still works + + Code + res_legacy <- closeness(g, vids = 1:3) + Condition + Warning: + The `vids` argument of `closeness()` is deprecated as of igraph 3.0.0. + i Please use the `vertices` argument instead. + diff --git a/tests/testthat/_snaps/structural-properties.md b/tests/testthat/_snaps/structural-properties.md index 13b5bc079bf..42e969a4446 100644 --- a/tests/testthat/_snaps/structural-properties.md +++ b/tests/testthat/_snaps/structural-properties.md @@ -73,3 +73,21 @@ [2,] -210 590 -380 [3,] -200 -380 580 +# degree(v = ) is deprecated but still works + + Code + res_legacy <- degree(g, v = 1:3) + Condition + Warning: + The `v` argument of `degree()` is deprecated as of igraph 3.0.0. + i Please use the `vertices` argument instead. + +# degree() rejects `vertices` supplied both directly and as `v` + + Code + degree(g, vertices = 1:3, v = 1:3) + Condition + Error in `degree()`: + ! Argument `vertices` of `degree()` was supplied more than once. + i It was also supplied via its legacy name `v`. + diff --git a/tests/testthat/test-centrality.R b/tests/testthat/test-centrality.R index 94b24ca791c..d38c2b7e64b 100644 --- a/tests/testthat/test-centrality.R +++ b/tests/testthat/test-centrality.R @@ -967,7 +967,7 @@ test_that("betweenness() covers migrated tail args and positional recovery", { res <- betweenness( ring, - v = V(ring)[1:3], + vertices = V(ring)[1:3], directed = FALSE, weights = rep(1, 5), normalized = TRUE, @@ -996,7 +996,7 @@ test_that("closeness() covers migrated tail args and positional recovery", { res <- closeness( path, - vids = V(path)[3], + vertices = V(path)[3], mode = "in", weights = c(1, 1), normalized = TRUE, @@ -1008,7 +1008,7 @@ test_that("closeness() covers migrated tail args and positional recovery", { expect_equal( closeness( path, - vids = V(path)[3], + vertices = V(path)[3], mode = "in", weights = c(1, 1), cutoff = 1 @@ -1060,7 +1060,7 @@ test_that("harmonic_centrality() covers migrated tail args and positional recove res <- harmonic_centrality( path, - vids = V(path)[3], + vertices = V(path)[3], mode = "in", weights = c(1, 1), normalized = TRUE, @@ -1072,7 +1072,7 @@ test_that("harmonic_centrality() covers migrated tail args and positional recove expect_equal( harmonic_centrality( path, - vids = V(path)[3], + vertices = V(path)[3], mode = "in", weights = c(1, 1), normalized = TRUE, @@ -1099,7 +1099,7 @@ test_that("page_rank() covers migrated tail args and positional recovery", { res <- page_rank( star, algorithm = "prpack", - vids = V(star)[1:5], + vertices = V(star)[1:5], directed = FALSE, damping = 0.9, personalized = c(1, rep(0, 9)), @@ -1145,7 +1145,7 @@ test_that("strength() covers migrated tail args and positional recovery", { res <- strength( star, - vids = V(star)[1:3], + vertices = V(star)[1:3], mode = "out", loops = FALSE, weights = 1:6 @@ -1156,7 +1156,7 @@ test_that("strength() covers migrated tail args and positional recovery", { expect_equal( strength( star, - vids = V(star)[1:3], + vertices = V(star)[1:3], mode = "out", loops = TRUE, weights = 1:6 @@ -1174,7 +1174,7 @@ test_that("diversity() covers migrated tail args and positional recovery", { rlang::local_options(lifecycle_verbosity = "warning") ring <- make_ring(10) - res <- diversity(ring, weights = 1:10, vids = V(ring)[1:4]) + res <- diversity(ring, weights = 1:10, vertices = V(ring)[1:4]) # Scaled entropy of the two incident edge weights, e.g. {10, 1} for vertex 1. expect_equal( res, @@ -1215,7 +1215,7 @@ test_that("power_centrality() covers migrated tail args and positional recovery" res <- power_centrality( ring, - nodes = V(ring)[1:3], + vertices = V(ring)[1:3], loops = FALSE, exponent = 0.2, normalized = TRUE, @@ -1230,7 +1230,7 @@ test_that("power_centrality() covers migrated tail args and positional recovery" lifecycle::expect_deprecated( res_legacy <- power_centrality( ring, - nodes = V(ring)[1:3], + vertices = V(ring)[1:3], exponent = 0.2, rescale = TRUE, sparse = FALSE, @@ -1273,7 +1273,7 @@ test_that("alpha_centrality() covers migrated tail args and positional recovery" # The scores are linear in the exogenous input. res <- alpha_centrality( dag, - nodes = V(dag)[1:3], + vertices = V(dag)[1:3], alpha = 0.5, loops = TRUE, exo = 2, @@ -1299,3 +1299,50 @@ test_that("alpha_centrality() covers migrated tail args and positional recovery" ) expect_identical(res_legacy, alpha_centrality(dag, V(dag), alpha = 0.75)) }) + +# ---- vertex selector rename: v/vids/nodes -> vertices ----------------- + +test_that("closeness(vids = ) is deprecated but still works", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + expect_snapshot( + res_legacy <- closeness(g, vids = 1:3) + ) + expect_identical(res_legacy, closeness(g, vertices = 1:3)) +}) + +test_that("betweenness(v = ) and strength(vids = ) are deprecated but still work", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + + lifecycle::expect_deprecated( + res_legacy <- betweenness(g, v = 1:3) + ) + expect_identical(res_legacy, betweenness(g, vertices = 1:3)) + + lifecycle::expect_deprecated( + res_legacy <- strength(g, vids = 1:3) + ) + expect_identical(res_legacy, strength(g, vertices = 1:3)) +}) + +test_that("power_centrality(nodes = ) is deprecated but still works", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + lifecycle::expect_deprecated( + res_legacy <- power_centrality(g, nodes = 1:3, exponent = 0.2) + ) + expect_identical( + res_legacy, + power_centrality(g, vertices = 1:3, exponent = 0.2) + ) +}) + +test_that("page_rank(vids = ) is recovered as `vertices`", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + lifecycle::expect_deprecated( + res_legacy <- page_rank(g, vids = 1:3) + ) + expect_identical(res_legacy, page_rank(g, vertices = 1:3)) +}) diff --git a/tests/testthat/test-constant-defaults.R b/tests/testthat/test-constant-defaults.R index f8770f4eb44..55c14f7e642 100644 --- a/tests/testthat/test-constant-defaults.R +++ b/tests/testthat/test-constant-defaults.R @@ -9,11 +9,11 @@ test_that("NULL selector defaults stand for the full vertex/edge set", { # Passing NULL explicitly is now the same as not passing the argument. # (Before the constant-defaults cleanup an explicit NULL was coerced to an # empty selection -- an accident of as_igraph_vs(), never documented.) - expect_identical(degree(g, v = NULL), degree(g)) - expect_identical(distances(g, v = NULL, to = NULL), distances(g)) - expect_identical(diversity(g, vids = NULL), diversity(g)) + expect_identical(degree(g, vertices = NULL), degree(g)) + expect_identical(distances(g, vertices = NULL, to = NULL), distances(g)) + expect_identical(diversity(g, vertices = NULL), diversity(g)) expect_identical(which_mutual(g, eids = NULL), which_mutual(g)) - expect_identical(closeness(g, vids = NULL), closeness(g)) + expect_identical(closeness(g, vertices = NULL), closeness(g)) }) test_that("NULL non-selector defaults resolve in the body", { @@ -33,13 +33,13 @@ test_that("NULL non-selector defaults resolve in the body", { test_that("NULL selector defaults of round-2 functions select the full set", { g <- make_ring(5) - expect_identical(max_degree(g, v = NULL), max_degree(g)) + expect_identical(max_degree(g, vertices = NULL), max_degree(g)) expect_identical(which_loop(g, eids = NULL), which_loop(g)) expect_identical(which_multiple(g, eids = NULL), which_multiple(g)) expect_identical(count_multiple(g, eids = NULL), count_multiple(g)) - expect_identical(count_triangles(g, vids = NULL), count_triangles(g)) - expect_identical(cocitation(g, v = NULL), cocitation(g)) - expect_identical(similarity(g, vids = NULL), similarity(g)) + expect_identical(count_triangles(g, vertices = NULL), count_triangles(g)) + expect_identical(cocitation(g, vertices = NULL), cocitation(g)) + expect_identical(similarity(g, vertices = NULL), similarity(g)) expect_identical_graphs(reverse_edges(g, eids = NULL), reverse_edges(g)) V(g)$name <- letters[1:5] @@ -82,9 +82,9 @@ test_that("empty-sequence defaults are spelled as typed empty vectors", { # NULL: an explicit empty selection keeps meaning "nothing selected", # while NULL now always means "use the default". g <- make_graph(c(1, 2, 2, 2, 2, 3), directed = TRUE) - expect_equal(max_degree(g, v = integer()), 0) + expect_equal(max_degree(g, vertices = integer()), 0) expect_identical(which_loop(g, eids = integer()), logical(0)) - expect_gt(max_degree(g, v = NULL), 0) + expect_gt(max_degree(g, vertices = NULL), 0) # layout_as_tree(): the typed empty stays the documented default tree <- make_tree(5) @@ -106,5 +106,5 @@ test_that("positional recovery of a selector with a NULL default works", { lifecycle::expect_deprecated( res <- diversity(g, NULL, V(g)[1:3]) ) - expect_identical(res, diversity(g, weights = NULL, vids = V(g)[1:3])) + expect_identical(res, diversity(g, weights = NULL, vertices = V(g)[1:3])) }) diff --git a/tests/testthat/test-efficiency.R b/tests/testthat/test-efficiency.R index 0d05c2ff558..3ab4a44cfe1 100644 --- a/tests/testthat/test-efficiency.R +++ b/tests/testthat/test-efficiency.R @@ -57,7 +57,7 @@ test_that("local_efficiency() covers vids, weights and directed", { # the neighbors of vertex 2 reconnect at distance 7 # and those of vertex 4 at distance 3. expect_equal( - local_efficiency(g, vids = c(2, 4), weights = 1:4, directed = FALSE), + local_efficiency(g, vertices = c(2, 4), weights = 1:4, directed = FALSE), c(1 / 7, 1 / 3) ) }) diff --git a/tests/testthat/test-interface.R b/tests/testthat/test-interface.R index a9c36f18c90..29cc6ecb9ac 100644 --- a/tests/testthat/test-interface.R +++ b/tests/testthat/test-interface.R @@ -109,7 +109,7 @@ test_that("adjacent_vertices works", { g <- sample_gnp(100, 20 / 100) al <- as_adj_list(g, mode = "all") test_vertices <- c(1, 7, 38, 75, 99) - adj_vertices <- adjacent_vertices(g, v = test_vertices) + adj_vertices <- adjacent_vertices(g, vertices = test_vertices) expect_s3_class(adj_vertices[[1]], "igraph.vs") for (i in seq_along(test_vertices)) { expect_setequal(adj_vertices[[i]], al[[test_vertices[i]]]) @@ -121,7 +121,7 @@ test_that("adjacent_vertices works", { al <- as_adj_list(g, mode = "all") test_vertices <- c(1, 7, 38, 75, 99) - adj_vertices <- adjacent_vertices(g, v = test_vertices) + adj_vertices <- adjacent_vertices(g, vertices = test_vertices) expect_s3_class(adj_vertices[[1]], NA) for (i in seq_along(test_vertices)) { expect_setequal(adj_vertices[[i]], al[[test_vertices[i]]]) @@ -134,7 +134,7 @@ test_that("incident_edges works", { g <- sample_gnp(100, 20 / 100) el <- as_adj_edge_list(g, mode = "all") test_vertices <- c(1, 7, 38, 75, 99) - inc_edges <- incident_edges(g, v = test_vertices) + inc_edges <- incident_edges(g, vertices = test_vertices) expect_s3_class(inc_edges[[1]], "igraph.es") for (i in seq_along(test_vertices)) { expect_setequal(inc_edges[[i]], el[[test_vertices[i]]]) @@ -146,7 +146,7 @@ test_that("incident_edges works", { el <- as_adj_edge_list(g, mode = "all") test_vertices <- c(1, 7, 38, 75, 99) - inc_edges <- incident_edges(g, v = test_vertices) + inc_edges <- incident_edges(g, vertices = test_vertices) expect_s3_class(inc_edges[[1]], NA) for (i in seq_along(test_vertices)) { expect_setequal(inc_edges[[i]], el[[test_vertices[i]]]) @@ -364,3 +364,20 @@ test_that("get_edge_ids() tail arguments and legacy positional recovery", { ) expect_identical(res, get_edge_ids(g, c(2, 1), directed = FALSE)) }) + +# ---- vertex selector rename: v -> vertices ---------------------------- + +test_that("adjacent_vertices(v = ) and delete_vertices(v = ) are deprecated but still work", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + + lifecycle::expect_deprecated( + res_legacy <- adjacent_vertices(g, v = 1:2) + ) + expect_equal(res_legacy, adjacent_vertices(g, vertices = 1:2)) + + lifecycle::expect_deprecated( + g_legacy <- delete_vertices(g, v = 1:2) + ) + expect_identical_graphs(g_legacy, delete_vertices(g, vertices = 1:2)) +}) diff --git a/tests/testthat/test-iterators.R b/tests/testthat/test-iterators.R index 59a6a274fee..3fd8f91060e 100644 --- a/tests/testthat/test-iterators.R +++ b/tests/testthat/test-iterators.R @@ -404,7 +404,7 @@ test_that("unconnected vs/es can be reused with the same graph", { load(tmp) - expect_equal(degree(g, v = vs), rep(2, 10)) + expect_equal(degree(g, vertices = vs), rep(2, 10)) expect_identical_graphs( delete_edges(g, es), delete_edges(g, 1:5) diff --git a/tests/testthat/test-similarity.R b/tests/testthat/test-similarity.R index 3e741a0055d..795f769ab9d 100644 --- a/tests/testthat/test-similarity.R +++ b/tests/testthat/test-similarity.R @@ -38,7 +38,7 @@ test_that("similarity() covers vids, mode, loops and method", { # so consecutive vertices share exactly one of their two out-neighbors. sim <- similarity( g, - vids = V(g)[1:3], + vertices = V(g)[1:3], mode = "out", loops = TRUE, method = "dice" diff --git a/tests/testthat/test-structural-properties.R b/tests/testthat/test-structural-properties.R index d1a5424489e..2ec694687b9 100644 --- a/tests/testthat/test-structural-properties.R +++ b/tests/testthat/test-structural-properties.R @@ -69,8 +69,8 @@ test_that("max_degree() works", { expect_equal(max_degree(g, loops = FALSE), 2) expect_equal(max_degree(g, mode = "out", loops = FALSE), 1) expect_equal(max_degree(g, mode = "in", loops = FALSE), 1) - expect_equal(max_degree(g, v = integer()), 0) - expect_equal(max_degree(g, v = NULL), max_degree(g)) + expect_equal(max_degree(g, vertices = integer()), 0) + expect_equal(max_degree(g, vertices = NULL), max_degree(g)) expect_equal(max_degree(make_empty_graph()), 0) }) @@ -352,7 +352,7 @@ test_that("farthest_vertices() works", { expect_equal(fn, list(vertices = c(1, 10), distance = 4)) expect_equal( - distances(kite, v = fn$vertices[1], to = fn$vertices[2])[1], + distances(kite, vertices = fn$vertices[1], to = fn$vertices[2])[1], fn$distance ) expect_equal(diameter(kite), fn$distance) @@ -510,7 +510,7 @@ test_that("transitivity() works", { t2 <- transitivity(g, type = "average") expect_equal(t2, 0.10159943848720931481) - t3 <- transitivity(g, type = "local", vids = V(g)) + t3 <- transitivity(g, type = "local", vertices = V(g)) t33 <- transitivity(g, type = "local") est3 <- structure( c(0, 0.06667, 0.1028, 0.1016, 0.1333, 0.2222), @@ -547,10 +547,10 @@ test_that("local transitivity() produces named vectors", { expect_named(t2, V(g)$name) vs <- c("a", "c") - t3 <- transitivity(g, type = "local", vids = vs) + t3 <- transitivity(g, type = "local", vertices = vs) expect_named(t3, vs) - t4 <- transitivity(g, type = "barrat", vids = vs) + t4 <- transitivity(g, type = "barrat", vertices = vs) expect_named(t4, vs) }) @@ -1194,7 +1194,7 @@ test_that("distances() legacy positional recovery", { g <- make_ring(5, directed = TRUE) lifecycle::expect_deprecated(res <- distances(g, V(g), V(g), "out")) - expect_identical(res, distances(g, v = V(g), to = V(g), mode = "out")) + expect_identical(res, distances(g, vertices = V(g), to = V(g), mode = "out")) }) test_that("shortest_paths() tail arguments and legacy positional recovery", { @@ -1284,7 +1284,7 @@ test_that("transitivity() tail arguments and legacy positional recovery", { transitivity( g, type = "barrat", - vids = V(g), + vertices = V(g), weights = rep(1, 4), isolates = "zero" ), @@ -1292,7 +1292,7 @@ test_that("transitivity() tail arguments and legacy positional recovery", { ) lifecycle::expect_deprecated(res <- transitivity(g, "local", V(g))) - expect_identical(res, transitivity(g, type = "local", vids = V(g))) + expect_identical(res, transitivity(g, type = "local", vertices = V(g))) }) test_that("constraint() tail arguments and legacy positional recovery", { @@ -1302,7 +1302,7 @@ test_that("constraint() tail arguments and legacy positional recovery", { # Explicit unit weights override the weight attribute: # every vertex of an unweighted triangle has constraint 1.125. expect_equal( - constraint(g, nodes = V(g), weights = rep(1, 3)), + constraint(g, vertices = V(g), weights = rep(1, 3)), c(a = 1.125, b = 1.125, c = 1.125) ) @@ -1333,7 +1333,10 @@ test_that("edge_density() tail arguments and legacy positional recovery", { test_that("ego_size() tail arguments and legacy positional recovery", { g <- make_ring(5, directed = TRUE) - expect_equal(ego_size(g, order = 1, nodes = 1, mode = "out", mindist = 1), 1) + expect_equal( + ego_size(g, order = 1, vertices = 1, mode = "out", mindist = 1), + 1 + ) lifecycle::expect_deprecated(res <- ego_size(g, 1, 1, "out")) expect_identical(res, ego_size(g, 1, 1, mode = "out")) @@ -1342,7 +1345,7 @@ test_that("ego_size() tail arguments and legacy positional recovery", { test_that("ego() tail arguments and legacy positional recovery", { g <- make_ring(5, directed = TRUE) - e <- ego(g, order = 1, nodes = 1, mode = "out", mindist = 1) + e <- ego(g, order = 1, vertices = 1, mode = "out", mindist = 1) expect_equal(as.numeric(e[[1]]), 2) lifecycle::expect_deprecated(res <- ego(g, 1, 1, "out")) @@ -1352,7 +1355,7 @@ test_that("ego() tail arguments and legacy positional recovery", { test_that("make_ego_graph() tail arguments and legacy positional recovery", { g <- make_ring(5, directed = TRUE) - mg <- make_ego_graph(g, order = 1, nodes = 1, mode = "out", mindist = 1) + mg <- make_ego_graph(g, order = 1, vertices = 1, mode = "out", mindist = 1) expect_length(mg, 1) expect_equal(vcount(mg[[1]]), 1) expect_equal(ecount(mg[[1]]), 0) @@ -1542,7 +1545,7 @@ test_that("knn() tail arguments and legacy positional recovery", { # only the centre has out-neighbours, each with in-degree 1. r <- knn( g, - vids = V(g), + vertices = V(g), mode = "out", neighbor.degree.mode = "in", weights = NA @@ -1553,3 +1556,65 @@ test_that("knn() tail arguments and legacy positional recovery", { lifecycle::expect_deprecated(res <- knn(g, V(g), "out")) expect_identical(res, knn(g, V(g), mode = "out")) }) + +# ---- vertex selector rename: v/vids/nodes -> vertices ----------------- + +test_that("degree(v = ) is deprecated but still works", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + expect_snapshot( + res_legacy <- degree(g, v = 1:3) + ) + expect_identical(res_legacy, degree(g, vertices = 1:3)) +}) + +test_that("degree() rejects `vertices` supplied both directly and as `v`", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + expect_snapshot( + degree(g, vertices = 1:3, v = 1:3), + error = TRUE + ) +}) + +test_that("ego(nodes = ) and induced_subgraph(vids = ) are deprecated but still work", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + + lifecycle::expect_deprecated( + res_legacy <- ego(g, order = 1, nodes = 1:3) + ) + expect_equal(res_legacy, ego(g, order = 1, vertices = 1:3)) + + lifecycle::expect_deprecated( + res_legacy <- induced_subgraph(g, vids = 1:5) + ) + expect_identical_graphs(res_legacy, induced_subgraph(g, vertices = 1:5)) +}) + +test_that("distances(v = ) and max_degree(v = ) are deprecated but still work", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_ring(10) + + lifecycle::expect_deprecated( + res_legacy <- distances(g, v = 1:3) + ) + expect_identical(res_legacy, distances(g, vertices = 1:3)) + + lifecycle::expect_deprecated( + res_legacy <- max_degree(g, v = 1:3) + ) + expect_identical(res_legacy, max_degree(g, vertices = 1:3)) +}) + +test_that("transitivity(vids = ) is recovered as `vertices`", { + rlang::local_options(lifecycle_verbosity = "warning") + g <- make_graph(~ a - b - c - a - d) + lifecycle::expect_deprecated( + res_legacy <- transitivity(g, type = "local", vids = c("a", "c")) + ) + expect_identical( + res_legacy, + transitivity(g, type = "local", vertices = c("a", "c")) + ) +}) diff --git a/tools/migrations/centrality.R b/tools/migrations/centrality.R index 44d94eece58..29e29502e86 100644 --- a/tools/migrations/centrality.R +++ b/tools/migrations/centrality.R @@ -7,14 +7,15 @@ migrations <- list( old = function(graph, nodes, alpha, loops, exo, weights, tol, sparse) {}, new = function( graph, - nodes = NULL, + vertices = NULL, ..., alpha = 1, loops = FALSE, exo = 1, weights = NULL, tol = 1e-7, - sparse = TRUE + sparse = TRUE, + nodes = deprecated() ) {}, when = "3.0.0" ), @@ -23,12 +24,13 @@ migrations <- list( old = function(graph, v, directed, weights, normalized, cutoff) {}, new = function( graph, - v = NULL, + vertices = NULL, ..., directed = TRUE, weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + v = deprecated() ) {}, when = "3.0.0" ), @@ -37,23 +39,24 @@ migrations <- list( old = function(graph, vids, mode, weights, normalized, cutoff) {}, new = function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("out", "in", "all", "total"), weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + vids = deprecated() ) {}, when = "3.0.0" ), diversity = list( - old = function(graph, weights, vids) {}, + old = function(graph, weights, vids = vertices) {}, new = function( graph, ..., weights = NULL, - vids = NULL + vertices = NULL ) {}, when = "3.0.0" ), @@ -75,12 +78,13 @@ migrations <- list( old = function(graph, vids, mode, weights, normalized, cutoff) {}, new = function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("out", "in", "all", "total"), weights = NULL, normalized = FALSE, - cutoff = -1 + cutoff = -1, + vids = deprecated() ) {}, when = "3.0.0" ), @@ -89,7 +93,7 @@ migrations <- list( old = function( graph, algo = algorithm, - vids, + vids = vertices, directed, damping, personalized, @@ -100,7 +104,7 @@ migrations <- list( graph, ..., algorithm = c("prpack", "arpack"), - vids = NULL, + vertices = NULL, directed = TRUE, damping = 0.85, personalized = NULL, @@ -123,14 +127,15 @@ migrations <- list( ) {}, new = function( graph, - nodes = NULL, + vertices = NULL, ..., loops = FALSE, exponent = 1, normalized = FALSE, tol = 1e-7, sparse = TRUE, - weights = NULL + weights = NULL, + nodes = deprecated() ) {}, when = "3.0.0" ), @@ -139,11 +144,12 @@ migrations <- list( old = function(graph, vids, mode, loops, weights) {}, new = function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = TRUE, - weights = NULL + weights = NULL, + vids = deprecated() ) {}, when = "3.0.0" ), diff --git a/tools/migrations/interface.R b/tools/migrations/interface.R index f9af26fef85..b84ced9047c 100644 --- a/tools/migrations/interface.R +++ b/tools/migrations/interface.R @@ -7,9 +7,10 @@ migrations <- list( old = function(graph, v, mode) {}, new = function( graph, - v, + vertices, ..., - mode = c("out", "in", "all", "total") + mode = c("out", "in", "all", "total"), + v = deprecated() ) {}, when = "3.0.0" ), @@ -52,9 +53,10 @@ migrations <- list( old = function(graph, v, mode) {}, new = function( graph, - v, + vertices, ..., - mode = c("out", "in", "all", "total") + mode = c("out", "in", "all", "total"), + v = deprecated() ) {}, when = "3.0.0" ), diff --git a/tools/migrations/similarity-efficiency.R b/tools/migrations/similarity-efficiency.R index 18607786045..c1cebe7ea5d 100644 --- a/tools/migrations/similarity-efficiency.R +++ b/tools/migrations/similarity-efficiency.R @@ -52,11 +52,12 @@ migrations <- list( old = function(graph, vids, weights, directed, mode) {}, new = function( graph, - vids = NULL, + vertices = NULL, ..., weights = NULL, directed = TRUE, - mode = c("all", "out", "in", "total") + mode = c("all", "out", "in", "total"), + vids = deprecated() ) {}, when = "3.0.0" ), @@ -65,7 +66,7 @@ migrations <- list( old = function(graph, vids, mode, loops, method) {}, new = function( graph, - vids = NULL, + vertices = NULL, ..., mode = c( "all", @@ -78,7 +79,8 @@ migrations <- list( "jaccard", "dice", "invlogweighted" - ) + ), + vids = deprecated() ) {}, when = "3.0.0" ) diff --git a/tools/migrations/structural-properties.R b/tools/migrations/structural-properties.R index b0581d12904..961dbf48f88 100644 --- a/tools/migrations/structural-properties.R +++ b/tools/migrations/structural-properties.R @@ -86,9 +86,10 @@ migrations <- list( old = function(graph, nodes, weights) {}, new = function( graph, - nodes = NULL, + vertices = NULL, ..., - weights = NULL + weights = NULL, + nodes = deprecated() ) {}, when = "3.0.0" ), @@ -127,11 +128,12 @@ migrations <- list( old = function(graph, v, mode, loops, normalized) {}, new = function( graph, - v = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), loops = TRUE, - normalized = FALSE + normalized = FALSE, + v = deprecated() ) {}, when = "3.0.0" ), @@ -152,7 +154,7 @@ migrations <- list( old = function(graph, v, to, mode, weights, algorithm) {}, new = function( graph, - v = NULL, + vertices = NULL, to = NULL, ..., mode = c("all", "out", "in"), @@ -164,7 +166,8 @@ migrations <- list( "bellman-ford", "johnson", "floyd-warshall" - ) + ), + v = deprecated() ) {}, when = "3.0.0" ), @@ -184,10 +187,11 @@ migrations <- list( new = function( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) {}, when = "3.0.0" ), @@ -197,10 +201,11 @@ migrations <- list( new = function( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) {}, when = "3.0.0" ), @@ -265,9 +270,10 @@ migrations <- list( old = function(graph, vids, impl) {}, new = function( graph, - vids, + vertices, ..., - impl = c("auto", "copy_and_delete", "create_from_scratch") + impl = c("auto", "copy_and_delete", "create_from_scratch"), + vids = deprecated() ) {}, when = "3.0.0" ), @@ -286,11 +292,12 @@ migrations <- list( old = function(graph, vids, mode, neighbor.degree.mode, weights) {}, new = function( graph, - vids = NULL, + vertices = NULL, ..., mode = c("all", "out", "in", "total"), neighbor.degree.mode = c("all", "out", "in", "total"), - weights = NULL + weights = NULL, + vids = deprecated() ) {}, when = "3.0.0" ), @@ -300,10 +307,11 @@ migrations <- list( new = function( graph, order = 1, - nodes = NULL, + vertices = NULL, ..., mode = c("all", "out", "in"), - mindist = 0 + mindist = 0, + nodes = deprecated() ) {}, when = "3.0.0" ), @@ -414,7 +422,7 @@ migrations <- list( ), transitivity = list( - old = function(graph, type, vids, weights, isolates) {}, + old = function(graph, type, vids = vertices, weights, isolates) {}, new = function( graph, type = c( @@ -430,7 +438,7 @@ migrations <- list( "weighted" ), ..., - vids = NULL, + vertices = NULL, weights = NULL, isolates = c("NaN", "zero") ) {}, diff --git a/vignettes/igraph.Rmd b/vignettes/igraph.Rmd index 6682bc6b3fc..196cf7a41cb 100644 --- a/vignettes/igraph.Rmd +++ b/vignettes/igraph.Rmd @@ -328,13 +328,13 @@ degree(g, 7) ``` ```{r echo = TRUE} -degree(g, v = c(3, 4, 5)) +degree(g, vertices = c(3, 4, 5)) ``` Most functions that accept vertex IDs also accept vertex _names_ (the values of the `name` vertex attribute) as long as the names are unique: ```{r echo = TRUE} -degree(g, v = c("Carmina", "Moshe", "Nang")) +degree(g, vertices = c("Carmina", "Moshe", "Nang")) ``` It also works for single vertices: diff --git a/vignettes/igraph_ES.rmd b/vignettes/igraph_ES.rmd index c102c204450..4ed608c10cc 100644 --- a/vignettes/igraph_ES.rmd +++ b/vignettes/igraph_ES.rmd @@ -340,13 +340,13 @@ degree(g, 7) ``` ```{r echo = TRUE} -degree(g, v = c(3,4,5)) +degree(g, vertices = c(3,4,5)) ``` La mayoría de las funciones que aceptan los IDs de los vértices también aceptan los "nombres" de los vértices (es decir, los valores del atributo `name` del vértice) siempre que los nombres sean únicos: ```{r echo = TRUE} -degree(g, v = c("Carmina", "Moshe", "Nang")) +degree(g, vertices = c("Carmina", "Moshe", "Nang")) ``` También funciona para vértices individuales: