From afbba71e812fa3be00c9af03946e118a934f3630 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Jul 2026 16:23:47 +0000 Subject: [PATCH] refactor: move optional arguments of centralization functions behind the ellipsis Insert `...` between the defining arguments and the optional modifiers of 6 functions, following the zoning rules in CONTRIBUTING.md. Legacy positional and abbreviated calls are recovered by the generated ARG_HANDLE blocks (registry: tools/migrations/centralization.R) and emit a single soft deprecation for igraph 3.0.0. No defaults change and no arguments are renamed. Functions: centr_betw, centr_betw_tmax, centr_clo, centr_clo_tmax, centr_degree, centralize Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016M32izVHZPfxAqemAe4BrX --- R/centralization.R | 169 +++++++++++++++++++++++++++++- R/cycles.R | 1 + man/centr_betw.Rd | 4 +- man/centr_betw_tmax.Rd | 4 +- man/centr_clo.Rd | 4 +- man/centr_clo_tmax.Rd | 9 +- man/centr_degree.Rd | 3 + man/centralize.Rd | 4 +- tools/migrations/centralization.R | 72 +++++++++++++ 9 files changed, 262 insertions(+), 8 deletions(-) create mode 100644 tools/migrations/centralization.R diff --git a/R/centralization.R b/R/centralization.R index f2c3b090149..55f23fed069 100644 --- a/R/centralization.R +++ b/R/centralization.R @@ -278,6 +278,7 @@ NULL #' a graph-level score from vertex-level scores. #' #' @param scores The vertex level centrality scores. +#' @inheritParams rlang::args_dots_empty #' @param theoretical.max Real scalar. The graph-level centralization measure of #' the most centralized graph with the same number of vertices as the graph #' under study. This is only used if the `normalized` argument is set @@ -314,7 +315,37 @@ NULL #' g1 <- make_star(10, mode = "undirected") #' centr_eigen(g0)$centralization #' centr_eigen(g1)$centralization -centralize <- function(scores, theoretical.max = 0, normalized = TRUE) { +centralize <- function( + scores, + ..., + theoretical.max = 0, + normalized = TRUE +) { + # BEGIN GENERATED ARG_HANDLE: centralize, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list( + theoretical.max = theoretical.max, + normalized = normalized + ), + recover_new = c("theoretical.max", "normalized"), + recover_old = c("theoretical.max", "normalized"), + match_names = c("theoretical.max", "normalized"), + match_to = c("theoretical.max", "normalized"), + defaults = list(theoretical.max = 0, normalized = TRUE), + head_args = c("scores"), + fn_name = "centralize" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + centralization_impl( scores = scores, theoretical_max = theoretical.max, @@ -327,6 +358,7 @@ centralize <- function(scores, theoretical.max = 0, normalized = TRUE) { #' See [centralize()] for a summary of graph centralization. #' #' @param graph The input graph. +#' @inheritParams rlang::args_dots_empty #' @param mode This is the same as the `mode` argument of #' `degree()`. #' @param loops Logical, whether to consider loops edges when @@ -363,10 +395,37 @@ centralize <- function(scores, theoretical.max = 0, normalized = TRUE) { #' centr_eigen(g, directed = FALSE)$centralization centr_degree <- function( graph, + ..., mode = c("all", "out", "in", "total"), loops = TRUE, normalized = TRUE ) { + # BEGIN GENERATED ARG_HANDLE: centr_degree, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(mode = mode, loops = loops, normalized = normalized), + recover_new = c("mode", "loops", "normalized"), + recover_old = c("mode", "loops", "normalized"), + match_names = c("mode", "loops", "normalized"), + match_to = c("mode", "loops", "normalized"), + defaults = list( + mode = c("all", "out", "in", "total"), + loops = TRUE, + normalized = TRUE + ), + head_args = c("graph"), + fn_name = "centr_degree" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + centralization_degree_impl( graph = graph, mode = mode, @@ -435,6 +494,7 @@ centr_degree_tmax <- function( #' See [centralize()] for a summary of graph centralization. #' #' @param graph The input graph. +#' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether to use directed shortest paths for #' calculating betweenness. #' @inheritParams centr_degree @@ -466,7 +526,34 @@ centr_degree_tmax <- function( #' centr_clo(g, mode = "all")$centralization #' centr_betw(g, directed = FALSE)$centralization #' centr_eigen(g, directed = FALSE)$centralization -centr_betw <- function(graph, directed = TRUE, normalized = TRUE) { +centr_betw <- function( + graph, + ..., + directed = TRUE, + normalized = TRUE +) { + # BEGIN GENERATED ARG_HANDLE: centr_betw, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(directed = directed, normalized = normalized), + recover_new = c("directed", "normalized"), + recover_old = c("directed", "normalized"), + match_names = c("directed", "normalized"), + match_to = c("directed", "normalized"), + defaults = list(directed = TRUE, normalized = TRUE), + head_args = c("graph"), + fn_name = "centr_betw" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + # Argument checks ensure_igraph(graph) @@ -491,6 +578,7 @@ centr_betw <- function(graph, directed = TRUE, normalized = TRUE) { #' `nodes` and `directed` are both given. #' @param nodes The number of vertices. This is ignored if the graph is #' given. +#' @inheritParams rlang::args_dots_empty #' @param directed Logical, whether to use directed shortest paths #' for calculating betweenness. Ignored if an undirected graph was #' given. @@ -508,7 +596,34 @@ centr_betw <- function(graph, directed = TRUE, normalized = TRUE) { #' centr_betw(g, normalized = FALSE)$centralization %>% #' `/`(centr_betw_tmax(g)) #' centr_betw(g, normalized = TRUE)$centralization -centr_betw_tmax <- function(graph = NULL, nodes = 0, directed = TRUE) { +centr_betw_tmax <- function( + graph = NULL, + nodes = 0, + ..., + directed = TRUE +) { + # BEGIN GENERATED ARG_HANDLE: centr_betw_tmax, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(directed = directed), + recover_new = c("directed"), + recover_old = c("directed"), + match_names = c("directed"), + match_to = c("directed"), + defaults = list(directed = TRUE), + head_args = c("graph", "nodes"), + fn_name = "centr_betw_tmax" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + centralization_betweenness_tmax_impl( graph = graph, nodes = nodes, @@ -521,6 +636,7 @@ centr_betw_tmax <- function(graph = NULL, nodes = 0, directed = TRUE) { #' See [centralize()] for a summary of graph centralization. #' #' @param graph The input graph. +#' @inheritParams rlang::args_dots_empty #' @param mode This is the same as the `mode` argument of #' `closeness()`. #' @inheritParams centr_degree @@ -554,9 +670,32 @@ centr_betw_tmax <- function(graph = NULL, nodes = 0, directed = TRUE) { #' centr_eigen(g, directed = FALSE)$centralization centr_clo <- function( graph, + ..., mode = c("out", "in", "all", "total"), normalized = TRUE ) { + # BEGIN GENERATED ARG_HANDLE: centr_clo, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(mode = mode, normalized = normalized), + recover_new = c("mode", "normalized"), + recover_old = c("mode", "normalized"), + match_names = c("mode", "normalized"), + match_to = c("mode", "normalized"), + defaults = list(mode = c("out", "in", "all", "total"), normalized = TRUE), + head_args = c("graph"), + fn_name = "centr_clo" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + centralization_closeness_impl( graph = graph, mode = mode, @@ -572,6 +711,7 @@ centr_clo <- function( #' `nodes` is given. #' @param nodes The number of vertices. This is ignored if the graph is #' given. +#' @inheritParams rlang::args_dots_empty #' @param mode This is the same as the `mode` argument of #' `closeness()`. Ignored if an undirected graph is given. #' @return Real scalar, the theoretical maximum (unnormalized) graph @@ -591,8 +731,31 @@ centr_clo <- function( centr_clo_tmax <- function( graph = NULL, nodes = 0, + ..., mode = c("out", "in", "all", "total") ) { + # BEGIN GENERATED ARG_HANDLE: centr_clo_tmax, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(mode = mode), + recover_new = c("mode"), + recover_old = c("mode"), + match_names = c("mode"), + match_to = c("mode"), + defaults = list(mode = c("out", "in", "all", "total")), + head_args = c("graph", "nodes"), + fn_name = "centr_clo_tmax" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + centralization_closeness_tmax_impl( graph = graph, nodes = nodes, diff --git a/R/cycles.R b/R/cycles.R index c3d65b5cae0..25356203038 100644 --- a/R/cycles.R +++ b/R/cycles.R @@ -31,6 +31,7 @@ #' a specific cycle. #' #' @param graph The input graph. +#' @inheritParams rlang::args_dots_empty #' @param mode Character constant specifying how to handle directed graphs. #' `out` follows edge directions, `in` follows edges in the reverse direction, #' and `all` ignores edge directions. Ignored in undirected graphs. diff --git a/man/centr_betw.Rd b/man/centr_betw.Rd index 72e1a570dbc..3b4190b3514 100644 --- a/man/centr_betw.Rd +++ b/man/centr_betw.Rd @@ -4,11 +4,13 @@ \alias{centr_betw} \title{Centralize a graph according to the betweenness of vertices} \usage{ -centr_betw(graph, directed = TRUE, normalized = TRUE) +centr_betw(graph, ..., directed = TRUE, normalized = TRUE) } \arguments{ \item{graph}{The input graph.} +\item{...}{These dots are for future extensions and must be empty.} + \item{directed}{Logical, whether to use directed shortest paths for calculating betweenness.} diff --git a/man/centr_betw_tmax.Rd b/man/centr_betw_tmax.Rd index e46b82a1618..6da3968daf7 100644 --- a/man/centr_betw_tmax.Rd +++ b/man/centr_betw_tmax.Rd @@ -4,7 +4,7 @@ \alias{centr_betw_tmax} \title{Theoretical maximum for betweenness centralization} \usage{ -centr_betw_tmax(graph = NULL, nodes = 0, directed = TRUE) +centr_betw_tmax(graph = NULL, nodes = 0, ..., directed = TRUE) } \arguments{ \item{graph}{The input graph. It can also be \code{NULL} if @@ -13,6 +13,8 @@ centr_betw_tmax(graph = NULL, nodes = 0, directed = TRUE) \item{nodes}{The number of vertices. This is ignored if the graph is given.} +\item{...}{These dots are for future extensions and must be empty.} + \item{directed}{Logical, whether to use directed shortest paths for calculating betweenness. Ignored if an undirected graph was given.} diff --git a/man/centr_clo.Rd b/man/centr_clo.Rd index ff9845546a4..e3f708d9ea7 100644 --- a/man/centr_clo.Rd +++ b/man/centr_clo.Rd @@ -4,11 +4,13 @@ \alias{centr_clo} \title{Centralize a graph according to the closeness of vertices} \usage{ -centr_clo(graph, mode = c("out", "in", "all", "total"), normalized = TRUE) +centr_clo(graph, ..., mode = c("out", "in", "all", "total"), normalized = TRUE) } \arguments{ \item{graph}{The input graph.} +\item{...}{These dots are for future extensions and must be empty.} + \item{mode}{This is the same as the \code{mode} argument of \code{closeness()}.} diff --git a/man/centr_clo_tmax.Rd b/man/centr_clo_tmax.Rd index c7a2b04b185..93fbe09cde8 100644 --- a/man/centr_clo_tmax.Rd +++ b/man/centr_clo_tmax.Rd @@ -4,7 +4,12 @@ \alias{centr_clo_tmax} \title{Theoretical maximum for closeness centralization} \usage{ -centr_clo_tmax(graph = NULL, nodes = 0, mode = c("out", "in", "all", "total")) +centr_clo_tmax( + graph = NULL, + nodes = 0, + ..., + mode = c("out", "in", "all", "total") +) } \arguments{ \item{graph}{The input graph. It can also be \code{NULL} if @@ -13,6 +18,8 @@ centr_clo_tmax(graph = NULL, nodes = 0, mode = c("out", "in", "all", "total")) \item{nodes}{The number of vertices. This is ignored if the graph is given.} +\item{...}{These dots are for future extensions and must be empty.} + \item{mode}{This is the same as the \code{mode} argument of \code{closeness()}. Ignored if an undirected graph is given.} } diff --git a/man/centr_degree.Rd b/man/centr_degree.Rd index a0c26a1e8f2..0bed80e5c17 100644 --- a/man/centr_degree.Rd +++ b/man/centr_degree.Rd @@ -6,6 +6,7 @@ \usage{ centr_degree( graph, + ..., mode = c("all", "out", "in", "total"), loops = TRUE, normalized = TRUE @@ -14,6 +15,8 @@ centr_degree( \arguments{ \item{graph}{The input graph.} +\item{...}{These dots are for future extensions and must be empty.} + \item{mode}{This is the same as the \code{mode} argument of \code{degree()}.} diff --git a/man/centralize.Rd b/man/centralize.Rd index 5df23809675..5574cc67f67 100644 --- a/man/centralize.Rd +++ b/man/centralize.Rd @@ -5,11 +5,13 @@ \alias{centralization} \title{Centralization of a graph} \usage{ -centralize(scores, theoretical.max = 0, normalized = TRUE) +centralize(scores, ..., theoretical.max = 0, normalized = TRUE) } \arguments{ \item{scores}{The vertex level centrality scores.} +\item{...}{These dots are for future extensions and must be empty.} + \item{theoretical.max}{Real scalar. The graph-level centralization measure of the most centralized graph with the same number of vertices as the graph under study. This is only used if the \code{normalized} argument is set diff --git a/tools/migrations/centralization.R b/tools/migrations/centralization.R new file mode 100644 index 00000000000..0844a295b1b --- /dev/null +++ b/tools/migrations/centralization.R @@ -0,0 +1,72 @@ +# Argument-signature migrations: centralization +# Schema: see tools/migrations.R. Regenerate with: +# Rscript tools/generate-migrations.R + +migrations <- list( + centr_betw = list( + old = function(graph, directed, normalized) {}, + new = function( + graph, + ..., + directed = TRUE, + normalized = TRUE + ) {}, + when = "3.0.0" + ), + + centr_betw_tmax = list( + old = function(graph, nodes, directed) {}, + new = function( + graph = NULL, + nodes = 0, + ..., + directed = TRUE + ) {}, + when = "3.0.0" + ), + + centr_clo = list( + old = function(graph, mode, normalized) {}, + new = function( + graph, + ..., + mode = c("out", "in", "all", "total"), + normalized = TRUE + ) {}, + when = "3.0.0" + ), + + centr_clo_tmax = list( + old = function(graph, nodes, mode) {}, + new = function( + graph = NULL, + nodes = 0, + ..., + mode = c("out", "in", "all", "total") + ) {}, + when = "3.0.0" + ), + + centr_degree = list( + old = function(graph, mode, loops, normalized) {}, + new = function( + graph, + ..., + mode = c("all", "out", "in", "total"), + loops = TRUE, + normalized = TRUE + ) {}, + when = "3.0.0" + ), + + centralize = list( + old = function(scores, theoretical.max, normalized) {}, + new = function( + scores, + ..., + theoretical.max = 0, + normalized = TRUE + ) {}, + when = "3.0.0" + ) +)