diff --git a/R/aaa-operators.R b/R/aaa-operators.R index 1c81fcd5262..94994feeaad 100644 --- a/R/aaa-operators.R +++ b/R/aaa-operators.R @@ -35,7 +35,7 @@ connect_neighborhood_impl <- function( contract_vertices_impl <- function( graph, mapping, - vertex_attr_comb = igraph_opt("vertex.attr.comb") + vertex_attr_comb = igraph_opt("vertex_attr_combine") ) { # Argument checks ensure_igraph(graph) @@ -245,7 +245,7 @@ simplify_impl <- function( graph, remove_multiple = TRUE, remove_loops = TRUE, - edge_attr_comb = igraph_opt("edge.attr.comb") + edge_attr_comb = igraph_opt("edge_attr_combine") ) { # Argument checks ensure_igraph(graph) diff --git a/R/aaa-structural.R b/R/aaa-structural.R index de9543e847b..21d3795e887 100644 --- a/R/aaa-structural.R +++ b/R/aaa-structural.R @@ -166,7 +166,7 @@ to_directed_impl <- function( to_undirected_impl <- function( graph, mode = c("collapse", "each", "mutual"), - edge_attr_comb = igraph_opt("edge.attr.comb") + edge_attr_comb = igraph_opt("edge_attr_combine") ) { # Argument checks ensure_igraph(graph) diff --git a/R/attributes.R b/R/attributes.R index a75f4d2be37..57be26b72a8 100644 --- a/R/attributes.R +++ b/R/attributes.R @@ -1364,7 +1364,7 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) { #' vertex/edge attributes in these cases. #' #' The functions that support the combination of attributes have one or two -#' extra arguments called `vertex.attr.comb` and/or `edge.attr.comb` +#' extra arguments called `vertex_attr_combine` and/or `edge_attr_combine` #' that specify how to perform the mapping of the attributes. E.g. #' [contract()] contracts many vertices into a single one, the #' attributes of the vertices can be combined and stores as the vertex @@ -1475,22 +1475,22 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) { #' igraph_options(print.edge.attributes = TRUE) #' #' ## new attribute is the sum of the old ones -#' simplify(g, edge.attr.comb = "sum") +#' simplify(g, edge_attr_combine = "sum") #' #' ## collect attributes into a string -#' simplify(g, edge.attr.comb = toString) +#' simplify(g, edge_attr_combine = toString) #' #' ## concatenate them into a vector, this creates a complex #' ## attribute -#' simplify(g, edge.attr.comb = "concat") +#' simplify(g, edge_attr_combine = "concat") #' #' E(g)$name <- letters[seq_len(ecount(g))] #' #' ## both attributes are collected into strings -#' simplify(g, edge.attr.comb = toString) +#' simplify(g, edge_attr_combine = toString) #' #' ## harmonic average of weights, names are dropped -#' simplify(g, edge.attr.comb = list( +#' simplify(g, edge_attr_combine = list( #' weight = function(x) length(x) / sum(1 / x), #' name = "ignore" #' )) diff --git a/R/community.R b/R/community.R index c966d54cff0..63b7c938ae8 100644 --- a/R/community.R +++ b/R/community.R @@ -3593,13 +3593,14 @@ communities <- groups.communities #' #' The attributes of the graph are kept. Graph and edge attributes are #' unchanged, vertex attributes are combined, according to the -#' `vertex.attr.comb` parameter. +#' `vertex_attr_combine` parameter. #' #' @param graph The input graph, it can be directed or undirected. #' @param mapping A numeric vector that specifies the mapping. Its elements #' correspond to the vertices, and for each element the ID in the new graph is #' given. -#' @param vertex.attr.comb Specifies how to combine the vertex attributes in +#' @inheritParams rlang::args_dots_empty +#' @param vertex_attr_combine Specifies how to combine the vertex attributes in #' the new graph. Please see [attribute.combination()] for details. #' @return A new graph object. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} @@ -3612,7 +3613,7 @@ communities <- groups.communities #' E(g)$weight <- runif(ecount(g)) #' #' g2 <- contract(g, rep(1:5, each = 2), -#' vertex.attr.comb = toString +#' vertex_attr_combine = toString #' ) #' #' ## graph and edge attributes are kept, vertex attributes are @@ -3624,12 +3625,35 @@ communities <- groups.communities contract <- function( graph, mapping, - vertex.attr.comb = igraph_opt("vertex.attr.comb") + ..., + vertex_attr_combine = igraph_opt("vertex_attr_combine") ) { + # BEGIN GENERATED ARG_HANDLE: contract, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(vertex_attr_combine = vertex_attr_combine), + recover_new = c("vertex_attr_combine"), + recover_old = c("vertex.attr.comb"), + match_names = c("vertex.attr.comb", "vertex_attr_combine"), + match_to = c("vertex_attr_combine", "vertex_attr_combine"), + defaults = list(vertex_attr_combine = igraph_opt("vertex_attr_combine")), + head_args = c("graph", "mapping"), + fn_name = "contract" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + contract_vertices_impl( graph = graph, mapping = mapping, - vertex_attr_comb = vertex.attr.comb + vertex_attr_comb = vertex_attr_combine ) } diff --git a/R/conversion.R b/R/conversion.R index 9f44f193617..df9701f04ef 100644 --- a/R/conversion.R +++ b/R/conversion.R @@ -698,7 +698,7 @@ as_edgelist <- function( #' E(g4)$weight <- seq_len(ecount(g4)) #' ug4 <- as_undirected(g4, #' mode = "mutual", -#' edge.attr.comb = list(weight = length) +#' edge_attr_combine = list(weight = length) #' ) #' print(ug4, e = TRUE) #' @@ -736,7 +736,8 @@ as_directed <- function( } #' @rdname as_directed -#' @param edge.attr.comb Specifies what to do with edge attributes, if +#' @inheritParams rlang::args_dots_empty +#' @param edge_attr_combine Specifies what to do with edge attributes, if #' `mode="collapse"` or `mode="mutual"`. In these cases many edges #' might be mapped to a single one in the new graph, and their attributes are #' combined. Please see [attribute.combination()] for details on @@ -745,8 +746,31 @@ as_directed <- function( as_undirected <- function( graph, mode = c("collapse", "each", "mutual"), - edge.attr.comb = igraph_opt("edge.attr.comb") + ..., + edge_attr_combine = igraph_opt("edge_attr_combine") ) { + # BEGIN GENERATED ARG_HANDLE: as_undirected, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(edge_attr_combine = edge_attr_combine), + recover_new = c("edge_attr_combine"), + recover_old = c("edge.attr.comb"), + match_names = c("edge.attr.comb", "edge_attr_combine"), + match_to = c("edge_attr_combine", "edge_attr_combine"), + defaults = list(edge_attr_combine = igraph_opt("edge_attr_combine")), + head_args = c("graph", "mode"), + fn_name = "as_undirected" + ) + 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) mode <- igraph_match_arg(mode) @@ -755,7 +779,7 @@ as_undirected <- function( res <- to_undirected_impl( graph = graph, mode = mode, - edge_attr_comb = edge.attr.comb + edge_attr_comb = edge_attr_combine ) res diff --git a/R/migrate-args.R b/R/migrate-args.R index dd585490caa..f8ea8236f2c 100644 --- a/R/migrate-args.R +++ b/R/migrate-args.R @@ -1,8 +1,8 @@ # Runtime helper behind the generated `# ... ARG_HANDLE` blocks (see -# tools/migrations.R, tools/generate-migrations.R). Hand-written and tested -# directly -- the generated blocks only carry the per-function configuration and -# call this. Kept a plain function (not an inline closure) so it is easy to step -# through in a debugger. +# tools/migrations/README.md, tools/generate-migrations.R). Hand-written and +# tested directly -- the generated blocks only carry the per-function +# configuration and call this. Kept a plain function (not an inline closure) so +# it is easy to step through in a debugger. # # Pure: it inspects `dots` against the supplied maps and returns the recovered # values plus the deprecation message parts, or NULL when there is nothing to diff --git a/R/migration-fixture.R b/R/migration-fixture.R index 9303f3c49f0..17cb521ebd9 100644 --- a/R/migration-fixture.R +++ b/R/migration-fixture.R @@ -1,5 +1,6 @@ -# Test fixture for the in-place argument-migration generator (tools/migrations.R, -# tools/generate-migrations.R). `migration_fixture()` carries a generated +# Test fixture for the in-place argument-migration generator +# (tools/migrations/fixture.R, tools/generate-migrations.R). +# `migration_fixture()` carries a generated # ARG_HANDLE block that recovers a legacy call to its pre-3.0.0 signature # f(graph, n, weight, kind, directed) -- now # f(graph, n, ..., weights, type, directed), with `weight` renamed to `weights` diff --git a/R/operators.R b/R/operators.R index 4560514a944..59218a4ff53 100644 --- a/R/operators.R +++ b/R/operators.R @@ -275,7 +275,7 @@ apply_one_combiner <- function(comb, x) { #' function. For graphs that lack some vertex/edge attribute, the corresponding #' values in the new graph are set to a missing value (`NA` for scalar attributes, #' `NULL` for list attributes). Graph attributes are combined according to -#' `graph.attr.comb`; by default any name clash is resolved by adding +#' `graph_attr_combine`; by default any name clash is resolved by adding #' suffixes (`_1`, `_2`, ...). See [igraph-attribute-combination] for the #' available combiners. #' @@ -289,8 +289,8 @@ apply_one_combiner <- function(comb, x) { #' @aliases %du% #' @param \dots Graph objects or lists of graph objects. #' @param x,y Graph objects. -#' @param graph.attr.comb Specification for combining shared graph attributes. -#' Defaults to the `graph.attr.comb` igraph option (`"rename"` unless changed +#' @param graph_attr_combine Specification for combining shared graph attributes. +#' Defaults to the `graph_attr_combine` igraph option (`"rename"` unless changed #' via [igraph_options()]), which preserves the historical behaviour of #' appending `_1`, `_2`, ... suffixes to clashing attribute names. See #' [igraph-attribute-combination] for the available combiners. @@ -309,7 +309,7 @@ apply_one_combiner <- function(comb, x) { #' @export disjoint_union <- function( ..., - graph.attr.comb = igraph_opt("graph.attr.comb") + graph_attr_combine = igraph_opt("graph_attr_combine") ) { graphs <- unlist( recursive = FALSE, @@ -323,11 +323,11 @@ disjoint_union <- function( res <- .Call(Rx_igraph_disjoint_union, graphs) ## Graph attributes - graph.attr.comb <- igraph.i.attribute.combination( - graph.attr.comb, + graph_attr_combine <- igraph.i.attribute.combination( + graph_attr_combine, allow_rename = TRUE ) - graph.attributes(res) <- combine.attrs("g", graphs, comb = graph.attr.comb) + graph.attributes(res) <- combine.attrs("g", graphs, comb = graph_attr_combine) ## Vertex attributes attr <- list() @@ -402,9 +402,9 @@ disjoint_union <- function( ..., byname, keep.all.vertices, - graph.attr.comb = "rename", - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = "rename", + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) { graphs <- unlist( recursive = FALSE, @@ -428,16 +428,16 @@ disjoint_union <- function( cli::cli_abort("Some graphs are not named.") } - graph.attr.comb <- igraph.i.attribute.combination( - graph.attr.comb, + graph_attr_combine <- igraph.i.attribute.combination( + graph_attr_combine, allow_rename = TRUE ) - vertex.attr.comb <- igraph.i.attribute.combination( - vertex.attr.comb, + vertex_attr_combine <- igraph.i.attribute.combination( + vertex_attr_combine, allow_rename = TRUE ) - edge.attr.comb <- igraph.i.attribute.combination( - edge.attr.comb, + edge_attr_combine <- igraph.i.attribute.combination( + edge_attr_combine, allow_rename = TRUE ) @@ -471,14 +471,14 @@ disjoint_union <- function( graph.attributes(res) <- combine.attrs( "g", newgraphs, - comb = graph.attr.comb + comb = graph_attr_combine ) vertex.attributes(res) <- combine.attrs( "v", newgraphs, vcount(res), ignore = "name", - comb = vertex.attr.comb + comb = vertex_attr_combine ) V(res)$name <- uninames @@ -489,7 +489,7 @@ disjoint_union <- function( newgraphs, ecount(res), maps = maps, - comb = edge.attr.comb + comb = edge_attr_combine ) } } else { @@ -516,13 +516,13 @@ disjoint_union <- function( graph.attributes(res) <- combine.attrs( "g", graphs, - comb = graph.attr.comb + comb = graph_attr_combine ) vertex.attributes(res) <- combine.attrs( "v", graphs, vcount(res), - comb = vertex.attr.comb + comb = vertex_attr_combine ) ## Edges are a bit more difficult, we need a mapping @@ -532,7 +532,7 @@ disjoint_union <- function( graphs, ecount(res), maps = maps, - comb = edge.attr.comb + comb = edge_attr_combine ) } } @@ -582,8 +582,8 @@ union.default <- function(...) { #' `union()` keeps the attributes of all graphs. All graph, vertex and #' edge attributes are copied to the result. By default, if an attribute is #' present in multiple graphs and would result in a name clash, that attribute -#' is renamed by adding suffixes: `_1`, `_2`, etc. Pass `graph.attr.comb`, -#' `vertex.attr.comb` or `edge.attr.comb` to combine clashing attributes +#' is renamed by adding suffixes: `_1`, `_2`, etc. Pass `graph_attr_combine`, +#' `vertex_attr_combine` or `edge_attr_combine` to combine clashing attributes #' instead, e.g. by summing or by taking the first non-`NA` value. See #' [igraph-attribute-combination] for the available combiners. #' @@ -601,10 +601,10 @@ union.default <- function(...) { #' `auto`, that means `TRUE` if all graphs are named and `FALSE` #' otherwise. A warning is generated if `auto` and some (but not all) #' graphs are named. -#' @param graph.attr.comb,vertex.attr.comb,edge.attr.comb Specification for -#' combining clashing graph, vertex and edge attributes. `vertex.attr.comb` -#' and `edge.attr.comb` default to `"rename"`; `graph.attr.comb` defaults to -#' the `graph.attr.comb` igraph option (`"rename"` unless changed via +#' @param graph_attr_combine,vertex_attr_combine,edge_attr_combine Specification for +#' combining clashing graph, vertex and edge attributes. `vertex_attr_combine` +#' and `edge_attr_combine` default to `"rename"`; `graph_attr_combine` defaults to +#' the `graph_attr_combine` igraph option (`"rename"` unless changed via #' [igraph_options()]). `"rename"` preserves the historical behaviour of #' appending `_1`, `_2`, ... suffixes. See [igraph-attribute-combination] for #' the available combiners. @@ -626,18 +626,18 @@ union.default <- function(...) { union.igraph <- function( ..., byname = "auto", - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) { .igraph.graph.union.or.intersection( "union", ..., byname = byname, keep.all.vertices = TRUE, - graph.attr.comb = graph.attr.comb, - vertex.attr.comb = vertex.attr.comb, - edge.attr.comb = edge.attr.comb + graph_attr_combine = graph_attr_combine, + vertex_attr_combine = vertex_attr_combine, + edge_attr_combine = edge_attr_combine ) } @@ -683,7 +683,7 @@ intersection <- function(...) { #' vertex and edge attributes are copied to the result. By default, if an #' attribute is present in multiple graphs and would result in a name clash, #' that attribute is renamed by adding suffixes: `_1`, `_2`, etc. Pass -#' `graph.attr.comb`, `vertex.attr.comb` or `edge.attr.comb` to combine +#' `graph_attr_combine`, `vertex_attr_combine` or `edge_attr_combine` to combine #' clashing attributes instead; see [igraph-attribute-combination] for the #' available combiners. #' @@ -703,10 +703,10 @@ intersection <- function(...) { #' graphs are named. #' @param keep.all.vertices Logical, whether to keep vertices that only #' appear in a subset of the input graphs. -#' @param graph.attr.comb,vertex.attr.comb,edge.attr.comb Specification for -#' combining clashing graph, vertex and edge attributes. `vertex.attr.comb` -#' and `edge.attr.comb` default to `"rename"`; `graph.attr.comb` defaults to -#' the `graph.attr.comb` igraph option (`"rename"` unless changed via +#' @param graph_attr_combine,vertex_attr_combine,edge_attr_combine Specification for +#' combining clashing graph, vertex and edge attributes. `vertex_attr_combine` +#' and `edge_attr_combine` default to `"rename"`; `graph_attr_combine` defaults to +#' the `graph_attr_combine` igraph option (`"rename"` unless changed via #' [igraph_options()]). See [igraph-attribute-combination] for the available #' combiners. #' @return A new graph object. @@ -728,18 +728,18 @@ intersection.igraph <- function( ..., byname = "auto", keep.all.vertices = TRUE, - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) { .igraph.graph.union.or.intersection( "intersection", ..., byname = byname, keep.all.vertices = keep.all.vertices, - graph.attr.comb = graph.attr.comb, - vertex.attr.comb = vertex.attr.comb, - edge.attr.comb = edge.attr.comb + graph_attr_combine = graph_attr_combine, + vertex_attr_combine = vertex_attr_combine, + edge_attr_combine = edge_attr_combine ) } @@ -949,8 +949,8 @@ complementer <- function( #' `compose()` keeps the attributes of both graphs. All graph, vertex #' and edge attributes are copied to the result. By default, if an attribute #' is present in both graphs and would result in a name clash, that attribute -#' is renamed by adding suffixes: `_1`, `_2`. Pass `graph.attr.comb`, -#' `vertex.attr.comb` or `edge.attr.comb` to combine clashing attributes +#' is renamed by adding suffixes: `_1`, `_2`. Pass `graph_attr_combine`, +#' `vertex_attr_combine` or `edge_attr_combine` to combine clashing attributes #' instead; see [igraph-attribute-combination] for the available combiners. #' #' The `name` vertex attribute is treated specially if the operation is @@ -981,10 +981,10 @@ complementer <- function( #' `auto`, that means `TRUE` if both graphs are named and #' `FALSE` otherwise. A warning is generated if `auto` and one graph, #' but not both graphs are named. -#' @param graph.attr.comb,vertex.attr.comb,edge.attr.comb Specification for -#' combining clashing graph, vertex and edge attributes. `vertex.attr.comb` -#' and `edge.attr.comb` default to `"rename"`; `graph.attr.comb` defaults to -#' the `graph.attr.comb` igraph option (`"rename"` unless changed via +#' @param graph_attr_combine,vertex_attr_combine,edge_attr_combine Specification for +#' combining clashing graph, vertex and edge attributes. `vertex_attr_combine` +#' and `edge_attr_combine` default to `"rename"`; `graph_attr_combine` defaults to +#' the `graph_attr_combine` igraph option (`"rename"` unless changed via #' [igraph_options()]). See [igraph-attribute-combination] for the available #' combiners. #' @return A new graph object. @@ -1005,9 +1005,9 @@ compose <- function( g2, ..., byname = "auto", - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) { # BEGIN GENERATED ARG_HANDLE: compose, do not edit, see tools/generate-migrations.R if (...length() > 0L) { @@ -1015,15 +1015,15 @@ compose <- function( list(...), current = list( byname = byname, - graph.attr.comb = graph.attr.comb, - vertex.attr.comb = vertex.attr.comb, - edge.attr.comb = edge.attr.comb + graph_attr_combine = graph_attr_combine, + vertex_attr_combine = vertex_attr_combine, + edge_attr_combine = edge_attr_combine ), recover_new = c( "byname", - "graph.attr.comb", - "vertex.attr.comb", - "edge.attr.comb" + "graph_attr_combine", + "vertex_attr_combine", + "edge_attr_combine" ), recover_old = c( "byname", @@ -1032,22 +1032,28 @@ compose <- function( "edge.attr.comb" ), match_names = c( - "byname", "graph.attr.comb", "vertex.attr.comb", - "edge.attr.comb" + "edge.attr.comb", + "byname", + "graph_attr_combine", + "vertex_attr_combine", + "edge_attr_combine" ), match_to = c( + "graph_attr_combine", + "vertex_attr_combine", + "edge_attr_combine", "byname", - "graph.attr.comb", - "vertex.attr.comb", - "edge.attr.comb" + "graph_attr_combine", + "vertex_attr_combine", + "edge_attr_combine" ), defaults = list( byname = "auto", - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ), head_args = c("g1", "g2"), fn_name = "compose" @@ -1079,16 +1085,16 @@ compose <- function( cli::cli_abort("Some graphs are not named.") } - graph.attr.comb <- igraph.i.attribute.combination( - graph.attr.comb, + graph_attr_combine <- igraph.i.attribute.combination( + graph_attr_combine, allow_rename = TRUE ) - vertex.attr.comb <- igraph.i.attribute.combination( - vertex.attr.comb, + vertex_attr_combine <- igraph.i.attribute.combination( + vertex_attr_combine, allow_rename = TRUE ) - edge.attr.comb <- igraph.i.attribute.combination( - edge.attr.comb, + edge_attr_combine <- igraph.i.attribute.combination( + edge_attr_combine, allow_rename = TRUE ) @@ -1117,7 +1123,7 @@ compose <- function( res <- res$graph graphs <- list(g1, g2) - graph.attributes(res) <- combine.attrs("g", graphs, comb = graph.attr.comb) + graph.attributes(res) <- combine.attrs("g", graphs, comb = graph_attr_combine) if (byname) { vertex.attributes(res) <- combine.attrs( @@ -1125,7 +1131,7 @@ compose <- function( graphs, vcount(res), ignore = "name", - comb = vertex.attr.comb + comb = vertex_attr_combine ) V(res)$name <- uninames } else { @@ -1133,7 +1139,7 @@ compose <- function( "v", graphs, vcount(res), - comb = vertex.attr.comb + comb = vertex_attr_combine ) } @@ -1143,7 +1149,7 @@ compose <- function( graphs, ecount(res), maps2 = maps, - comb = edge.attr.comb + comb = edge_attr_combine ) } diff --git a/R/par.R b/R/par.R index 36bfd03fb14..f627ff556d4 100644 --- a/R/par.R +++ b/R/par.R @@ -61,9 +61,9 @@ getIgraphOpt <- function(x, default = NULL) { "print.edge.attributes" = FALSE, "print.graph.attributes" = FALSE, "verbose" = FALSE, - "graph.attr.comb" = "rename", - "vertex.attr.comb" = list(name = "concat", "ignore"), - "edge.attr.comb" = list(weight = "sum", name = "concat", "ignore"), + "graph_attr_combine" = "rename", + "vertex_attr_combine" = list(name = "concat", "ignore"), + "edge_attr_combine" = list(weight = "sum", name = "concat", "ignore"), "sparsematrices" = TRUE, "add.params" = TRUE, "add.vertex.names" = TRUE, @@ -76,6 +76,31 @@ getIgraphOpt <- function(x, default = NULL) { "print.style" = "cli" ) +# Option keys that were renamed to snake_case. Reading or setting an option by +# its old dotted name still works, but maps to the canonical key and emits a +# soft-deprecation. +.igraph.pars.aliases <- c( + "vertex.attr.comb" = "vertex_attr_combine", + "edge.attr.comb" = "edge_attr_combine" +) + +# Map any deprecated option names in `x` to their canonical keys, warning once +# per deprecated name encountered. +igraph_normalize_par_name <- function(x) { + for (i in seq_along(x)) { + new <- unname(.igraph.pars.aliases[x[i]]) + if (!is.na(new)) { + lifecycle::deprecate_soft( + "3.0.0", + I(paste0("The igraph option `", x[i], "`")), + I(paste0("the `", new, "` option")) + ) + x[i] <- new + } + } + x +} + igraph.pars.set.verbose <- function(verbose) { if (is.logical(verbose)) { .Call(Rx_igraph_set_verbose, verbose) @@ -139,12 +164,13 @@ igraph.pars.callbacks <- list("verbose" = igraph.pars.set.verbose) #' Possible values are \sQuote{auto} (the default), \sQuote{phylo}, \sQuote{hclust} and \sQuote{dendrogram}. #' See [plot_dendrogram()] for details. #' } -#' \item{edge.attr.comb}{ +#' \item{edge_attr_combine}{ #' Specifies what to do with the edge attributes if the graph is modified. #' The default value is `list(weight="sum", name="concat", "ignore")`. -#' See [attribute.combination()] for details on this. +#' See [attribute.combination()] for details on this. The former dotted +#' name `edge.attr.comb` still works but is soft-deprecated. #' } -#' \item{graph.attr.comb}{ +#' \item{graph_attr_combine}{ #' Specifies what to do with the graph attributes when graphs are #' combined, e.g. via [union()], [intersection()], [disjoint_union()] #' or [compose()]. The default value is `"rename"`, which resolves any @@ -188,10 +214,11 @@ igraph.pars.callbacks <- list("verbose" = igraph.pars.set.verbose) #' Logical constant, whether igraph functions should talk more than minimal. #' E.g. if `TRUE` then some functions will use progress bars while computing. Defaults to `FALSE`. #' } -#' \item{vertex.attr.comb}{ +#' \item{vertex_attr_combine}{ #' Specifies what to do with the vertex attributes if the graph is modified. #' The default value is `list(name="concat", "ignore")`. -#' See [attribute.combination()] for details on this. +#' See [attribute.combination()] for details on this. The former dotted +#' name `vertex.attr.comb` still works but is soft-deprecated. #' } #' } #' @@ -243,7 +270,7 @@ igraph_i_options <- function(..., .in = parent.frame()) { arg <- temp[[1]] if (mode(arg) == "character") { - return(.igraph.pars[arg]) + return(.igraph.pars[igraph_normalize_par_name(arg)]) } if (mode(arg) != "list") { @@ -262,6 +289,8 @@ igraph_i_options <- function(..., .in = parent.frame()) { if (is.null(n)) { cli::cli_abort("options must be given by name.") } + names(temp) <- igraph_normalize_par_name(n) + n <- names(temp) cb <- intersect(names(igraph.pars.callbacks), n) for (cn in cb) { temp[[cn]] <- igraph.pars.callbacks[[cn]](temp[[cn]]) @@ -324,6 +353,7 @@ igraph_opt <- function( } # END GENERATED ARG_HANDLE + x <- igraph_normalize_par_name(x) if (missing(default)) { get_config(paste0("igraph::", x), .igraph.pars[[x]]) } else { diff --git a/R/simple.R b/R/simple.R index dcc91205422..5b1680a7edd 100644 --- a/R/simple.R +++ b/R/simple.R @@ -68,7 +68,8 @@ is.simple <- function(graph) { #' @param remove.loops Logical, whether the loop edges are to be removed. #' @param remove.multiple Logical, whether the multiple edges are to be #' removed. -#' @param edge.attr.comb Specifies what to do with edge attributes, if +#' @inheritParams rlang::args_dots_empty +#' @param edge_attr_combine Specifies what to do with edge attributes, if #' `remove.multiple=TRUE`. In this case many edges might be mapped to a #' single one in the new graph, and their attributes are combined. Please see #' [attribute.combination()] for details on this. @@ -94,11 +95,34 @@ simplify <- function( graph, remove.multiple = TRUE, remove.loops = TRUE, - edge.attr.comb = igraph_opt("edge.attr.comb") + ..., + edge_attr_combine = igraph_opt("edge_attr_combine") ) { + # BEGIN GENERATED ARG_HANDLE: simplify, do not edit, see tools/generate-migrations.R + if (...length() > 0L) { + .arg_handle <- migrate_recover_args( + list(...), + current = list(edge_attr_combine = edge_attr_combine), + recover_new = c("edge_attr_combine"), + recover_old = c("edge.attr.comb"), + match_names = c("edge.attr.comb", "edge_attr_combine"), + match_to = c("edge_attr_combine", "edge_attr_combine"), + defaults = list(edge_attr_combine = igraph_opt("edge_attr_combine")), + head_args = c("graph", "remove.multiple", "remove.loops"), + fn_name = "simplify" + ) + list2env(.arg_handle$values, environment()) + lifecycle::deprecate_soft( + "3.0.0", + what = I(.arg_handle$what), + details = .arg_handle$details + ) + } + # END GENERATED ARG_HANDLE + # A graph that is already simple has no loops and no multiple edges, so # simplify_impl() would not change its structure regardless of the - # remove.* / edge.attr.comb arguments. Short-circuiting here avoids the + # remove.* / edge_attr_combine arguments. Short-circuiting here avoids the # cost of rebuilding the graph in the (common) already-simple case; # is_simple() is orders of magnitude cheaper than simplify(). if (is_simple(graph)) { @@ -108,7 +132,7 @@ simplify <- function( graph = graph, remove_multiple = remove.multiple, remove_loops = remove.loops, - edge_attr_comb = edge.attr.comb + edge_attr_comb = edge_attr_combine ) } diff --git a/R/structural-properties.R b/R/structural-properties.R index 578eed4bbc3..78d68ab3459 100644 --- a/R/structural-properties.R +++ b/R/structural-properties.R @@ -3197,7 +3197,7 @@ girth <- function( #' # Remove multiple edges but keep multiplicity #' g <- sample_pa(10, m = 3, algorithm = "bag") #' E(g)$weight <- count_multiple(g) -#' g <- simplify(g, edge.attr.comb = list(weight = "min")) +#' g <- simplify(g, edge_attr_combine = list(weight = "min")) #' any(which_multiple(g)) #' E(g)$weight #' diff --git a/man/as.undirected.Rd b/man/as.undirected.Rd index 1a0ae66f3f4..66f36118514 100644 --- a/man/as.undirected.Rd +++ b/man/as.undirected.Rd @@ -17,12 +17,6 @@ as.undirected( \code{as_directed()} it can be \code{mutual} or \code{arbitrary}. For \code{as_undirected()} it can be \code{each}, \code{collapse} or \code{mutual}. See details below.} - -\item{edge.attr.comb}{Specifies what to do with edge attributes, if -\code{mode="collapse"} or \code{mode="mutual"}. In these cases many edges -might be mapped to a single one in the new graph, and their attributes are -combined. Please see \code{\link[=attribute.combination]{attribute.combination()}} for details on -this.} } \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/as_directed.Rd b/man/as_directed.Rd index f4032e7956d..7d171c43c4a 100644 --- a/man/as_directed.Rd +++ b/man/as_directed.Rd @@ -10,7 +10,8 @@ as_directed(graph, ..., mode = c("mutual", "arbitrary", "random", "acyclic")) as_undirected( graph, mode = c("collapse", "each", "mutual"), - edge.attr.comb = igraph_opt("edge.attr.comb") + ..., + edge_attr_combine = igraph_opt("edge_attr_combine") ) } \arguments{ @@ -23,7 +24,7 @@ as_undirected( \code{as_undirected()} it can be \code{each}, \code{collapse} or \code{mutual}. See details below.} -\item{edge.attr.comb}{Specifies what to do with edge attributes, if +\item{edge_attr_combine}{Specifies what to do with edge attributes, if \code{mode="collapse"} or \code{mode="mutual"}. In these cases many edges might be mapped to a single one in the new graph, and their attributes are combined. Please see \code{\link[=attribute.combination]{attribute.combination()}} for details on @@ -117,7 +118,7 @@ g4 <- make_graph(c( E(g4)$weight <- seq_len(ecount(g4)) ug4 <- as_undirected(g4, mode = "mutual", - edge.attr.comb = list(weight = length) + edge_attr_combine = list(weight = length) ) print(ug4, e = TRUE) diff --git a/man/compose.Rd b/man/compose.Rd index ea67a1050ca..339e5e28eba 100644 --- a/man/compose.Rd +++ b/man/compose.Rd @@ -10,9 +10,9 @@ compose( g2, ..., byname = "auto", - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) } \arguments{ @@ -28,10 +28,10 @@ to perform the operation based on symbolic vertex names. If it is \code{FALSE} otherwise. A warning is generated if \code{auto} and one graph, but not both graphs are named.} -\item{graph.attr.comb, vertex.attr.comb, edge.attr.comb}{Specification for -combining clashing graph, vertex and edge attributes. \code{vertex.attr.comb} -and \code{edge.attr.comb} default to \code{"rename"}; \code{graph.attr.comb} defaults to -the \code{graph.attr.comb} igraph option (\code{"rename"} unless changed via +\item{graph_attr_combine, vertex_attr_combine, edge_attr_combine}{Specification for +combining clashing graph, vertex and edge attributes. \code{vertex_attr_combine} +and \code{edge_attr_combine} default to \code{"rename"}; \code{graph_attr_combine} defaults to +the \code{graph_attr_combine} igraph option (\code{"rename"} unless changed via \code{\link[=igraph_options]{igraph_options()}}). See \link{igraph-attribute-combination} for the available combiners.} } @@ -57,8 +57,8 @@ names. Otherwise numeric vertex IDs are used. \code{compose()} keeps the attributes of both graphs. All graph, vertex and edge attributes are copied to the result. By default, if an attribute is present in both graphs and would result in a name clash, that attribute -is renamed by adding suffixes: \verb{_1}, \verb{_2}. Pass \code{graph.attr.comb}, -\code{vertex.attr.comb} or \code{edge.attr.comb} to combine clashing attributes +is renamed by adding suffixes: \verb{_1}, \verb{_2}. Pass \code{graph_attr_combine}, +\code{vertex_attr_combine} or \code{edge_attr_combine} to combine clashing attributes instead; see \link{igraph-attribute-combination} for the available combiners. The \code{name} vertex attribute is treated specially if the operation is diff --git a/man/contract.Rd b/man/contract.Rd index 677567c3d0c..05488daa625 100644 --- a/man/contract.Rd +++ b/man/contract.Rd @@ -4,7 +4,12 @@ \alias{contract} \title{Contract several vertices into a single one} \usage{ -contract(graph, mapping, vertex.attr.comb = igraph_opt("vertex.attr.comb")) +contract( + graph, + mapping, + ..., + vertex_attr_combine = igraph_opt("vertex_attr_combine") +) } \arguments{ \item{graph}{The input graph, it can be directed or undirected.} @@ -13,7 +18,9 @@ contract(graph, mapping, vertex.attr.comb = igraph_opt("vertex.attr.comb")) correspond to the vertices, and for each element the ID in the new graph is given.} -\item{vertex.attr.comb}{Specifies how to combine the vertex attributes in +\item{...}{These dots are for future extensions and must be empty.} + +\item{vertex_attr_combine}{Specifies how to combine the vertex attributes in the new graph. Please see \code{\link[=attribute.combination]{attribute.combination()}} for details.} } \value{ @@ -26,7 +33,7 @@ vertices in the new graph correspond to sets of vertices in the input graph. \details{ The attributes of the graph are kept. Graph and edge attributes are unchanged, vertex attributes are combined, according to the -\code{vertex.attr.comb} parameter. +\code{vertex_attr_combine} parameter. } \section{Related documentation in the C library}{ \href{https://igraph.org/c/html/0.10.17/igraph-Operators.html#igraph_contract_vertices}{\code{contract_vertices()}} @@ -40,7 +47,7 @@ V(g)$name <- letters[1:vcount(g)] E(g)$weight <- runif(ecount(g)) g2 <- contract(g, rep(1:5, each = 2), - vertex.attr.comb = toString + vertex_attr_combine = toString ) ## graph and edge attributes are kept, vertex attributes are diff --git a/man/contract.vertices.Rd b/man/contract.vertices.Rd index 41c87032023..cbb9cd10580 100644 --- a/man/contract.vertices.Rd +++ b/man/contract.vertices.Rd @@ -16,9 +16,6 @@ contract.vertices( \item{mapping}{A numeric vector that specifies the mapping. Its elements correspond to the vertices, and for each element the ID in the new graph is given.} - -\item{vertex.attr.comb}{Specifies how to combine the vertex attributes in -the new graph. Please see \code{\link[=attribute.combination]{attribute.combination()}} for details.} } \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/disjoint_union.Rd b/man/disjoint_union.Rd index 7b0b040da91..f72701ae8ad 100644 --- a/man/disjoint_union.Rd +++ b/man/disjoint_union.Rd @@ -5,15 +5,15 @@ \alias{\%du\%} \title{Disjoint union of graphs} \usage{ -disjoint_union(..., graph.attr.comb = igraph_opt("graph.attr.comb")) +disjoint_union(..., graph_attr_combine = igraph_opt("graph_attr_combine")) x \%du\% y } \arguments{ \item{\dots}{Graph objects or lists of graph objects.} -\item{graph.attr.comb}{Specification for combining shared graph attributes. -Defaults to the \code{graph.attr.comb} igraph option (\code{"rename"} unless changed +\item{graph_attr_combine}{Specification for combining shared graph attributes. +Defaults to the \code{graph_attr_combine} igraph option (\code{"rename"} unless changed via \code{\link[=igraph_options]{igraph_options()}}), which preserves the historical behaviour of appending \verb{_1}, \verb{_2}, ... suffixes to clashing attribute names. See \link{igraph-attribute-combination} for the available combiners.} @@ -38,7 +38,7 @@ particular, it merges vertex and edge attributes using the \code{\link[vctrs:vec function. For graphs that lack some vertex/edge attribute, the corresponding values in the new graph are set to a missing value (\code{NA} for scalar attributes, \code{NULL} for list attributes). Graph attributes are combined according to -\code{graph.attr.comb}; by default any name clash is resolved by adding +\code{graph_attr_combine}; by default any name clash is resolved by adding suffixes (\verb{_1}, \verb{_2}, ...). See \link{igraph-attribute-combination} for the available combiners. diff --git a/man/igraph-attribute-combination.Rd b/man/igraph-attribute-combination.Rd index 03e5e10f460..b36ff376c89 100644 --- a/man/igraph-attribute-combination.Rd +++ b/man/igraph-attribute-combination.Rd @@ -13,7 +13,7 @@ vertex/edge attributes in these cases. } \details{ The functions that support the combination of attributes have one or two -extra arguments called \code{vertex.attr.comb} and/or \code{edge.attr.comb} +extra arguments called \code{vertex_attr_combine} and/or \code{edge_attr_combine} that specify how to perform the mapping of the attributes. E.g. \code{\link[=contract]{contract()}} contracts many vertices into a single one, the attributes of the vertices can be combined and stores as the vertex @@ -119,22 +119,22 @@ igraph_options(print.vertex.attributes = TRUE) igraph_options(print.edge.attributes = TRUE) ## new attribute is the sum of the old ones -simplify(g, edge.attr.comb = "sum") +simplify(g, edge_attr_combine = "sum") ## collect attributes into a string -simplify(g, edge.attr.comb = toString) +simplify(g, edge_attr_combine = toString) ## concatenate them into a vector, this creates a complex ## attribute -simplify(g, edge.attr.comb = "concat") +simplify(g, edge_attr_combine = "concat") E(g)$name <- letters[seq_len(ecount(g))] ## both attributes are collected into strings -simplify(g, edge.attr.comb = toString) +simplify(g, edge_attr_combine = toString) ## harmonic average of weights, names are dropped -simplify(g, edge.attr.comb = list( +simplify(g, edge_attr_combine = list( weight = function(x) length(x) / sum(1 / x), name = "ignore" )) diff --git a/man/igraph_options.Rd b/man/igraph_options.Rd index 8ba971f89fc..0cce7d7eccb 100644 --- a/man/igraph_options.Rd +++ b/man/igraph_options.Rd @@ -65,12 +65,13 @@ The plotting function to use when plotting community structure dendrograms via \ Possible values are \sQuote{auto} (the default), \sQuote{phylo}, \sQuote{hclust} and \sQuote{dendrogram}. See \code{\link[=plot_dendrogram]{plot_dendrogram()}} for details. } -\item{edge.attr.comb}{ +\item{edge_attr_combine}{ Specifies what to do with the edge attributes if the graph is modified. The default value is \code{list(weight="sum", name="concat", "ignore")}. -See \code{\link[=attribute.combination]{attribute.combination()}} for details on this. +See \code{\link[=attribute.combination]{attribute.combination()}} for details on this. The former dotted +name \code{edge.attr.comb} still works but is soft-deprecated. } -\item{graph.attr.comb}{ +\item{graph_attr_combine}{ Specifies what to do with the graph attributes when graphs are combined, e.g. via \code{\link[=union]{union()}}, \code{\link[=intersection]{intersection()}}, \code{\link[=disjoint_union]{disjoint_union()}} or \code{\link[=compose]{compose()}}. The default value is \code{"rename"}, which resolves any @@ -114,10 +115,11 @@ It is recommended, if the user works with larger graphs. Logical constant, whether igraph functions should talk more than minimal. E.g. if \code{TRUE} then some functions will use progress bars while computing. Defaults to \code{FALSE}. } -\item{vertex.attr.comb}{ +\item{vertex_attr_combine}{ Specifies what to do with the vertex attributes if the graph is modified. The default value is \code{list(name="concat", "ignore")}. -See \code{\link[=attribute.combination]{attribute.combination()}} for details on this. +See \code{\link[=attribute.combination]{attribute.combination()}} for details on this. The former dotted +name \code{vertex.attr.comb} still works but is soft-deprecated. } } } diff --git a/man/intersection.igraph.Rd b/man/intersection.igraph.Rd index 5dffbafe553..06d2632ab23 100644 --- a/man/intersection.igraph.Rd +++ b/man/intersection.igraph.Rd @@ -9,9 +9,9 @@ ..., byname = "auto", keep.all.vertices = TRUE, - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) } \arguments{ @@ -26,10 +26,10 @@ graphs are named.} \item{keep.all.vertices}{Logical, whether to keep vertices that only appear in a subset of the input graphs.} -\item{graph.attr.comb, vertex.attr.comb, edge.attr.comb}{Specification for -combining clashing graph, vertex and edge attributes. \code{vertex.attr.comb} -and \code{edge.attr.comb} default to \code{"rename"}; \code{graph.attr.comb} defaults to -the \code{graph.attr.comb} igraph option (\code{"rename"} unless changed via +\item{graph_attr_combine, vertex_attr_combine, edge_attr_combine}{Specification for +combining clashing graph, vertex and edge attributes. \code{vertex_attr_combine} +and \code{edge_attr_combine} default to \code{"rename"}; \code{graph_attr_combine} defaults to +the \code{graph_attr_combine} igraph option (\code{"rename"} unless changed via \code{\link[=igraph_options]{igraph_options()}}). See \link{igraph-attribute-combination} for the available combiners.} } @@ -53,7 +53,7 @@ of the internal numeric vertex IDs. vertex and edge attributes are copied to the result. By default, if an attribute is present in multiple graphs and would result in a name clash, that attribute is renamed by adding suffixes: \verb{_1}, \verb{_2}, etc. Pass -\code{graph.attr.comb}, \code{vertex.attr.comb} or \code{edge.attr.comb} to combine +\code{graph_attr_combine}, \code{vertex_attr_combine} or \code{edge_attr_combine} to combine clashing attributes instead; see \link{igraph-attribute-combination} for the available combiners. diff --git a/man/simplify.Rd b/man/simplify.Rd index bf1643497a5..fc4b7c6c4dc 100644 --- a/man/simplify.Rd +++ b/man/simplify.Rd @@ -10,7 +10,8 @@ simplify( graph, remove.multiple = TRUE, remove.loops = TRUE, - edge.attr.comb = igraph_opt("edge.attr.comb") + ..., + edge_attr_combine = igraph_opt("edge_attr_combine") ) is_simple(graph) @@ -25,7 +26,9 @@ removed.} \item{remove.loops}{Logical, whether the loop edges are to be removed.} -\item{edge.attr.comb}{Specifies what to do with edge attributes, if +\item{...}{These dots are for future extensions and must be empty.} + +\item{edge_attr_combine}{Specifies what to do with edge attributes, if \code{remove.multiple=TRUE}. In this case many edges might be mapped to a single one in the new graph, and their attributes are combined. Please see \code{\link[=attribute.combination]{attribute.combination()}} for details on this.} diff --git a/man/union.igraph.Rd b/man/union.igraph.Rd index 95aacbd76c1..5b1ff8a5c36 100644 --- a/man/union.igraph.Rd +++ b/man/union.igraph.Rd @@ -8,9 +8,9 @@ \method{union}{igraph}( ..., byname = "auto", - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) } \arguments{ @@ -22,10 +22,10 @@ to perform the operation based on symbolic vertex names. If it is otherwise. A warning is generated if \code{auto} and some (but not all) graphs are named.} -\item{graph.attr.comb, vertex.attr.comb, edge.attr.comb}{Specification for -combining clashing graph, vertex and edge attributes. \code{vertex.attr.comb} -and \code{edge.attr.comb} default to \code{"rename"}; \code{graph.attr.comb} defaults to -the \code{graph.attr.comb} igraph option (\code{"rename"} unless changed via +\item{graph_attr_combine, vertex_attr_combine, edge_attr_combine}{Specification for +combining clashing graph, vertex and edge attributes. \code{vertex_attr_combine} +and \code{edge_attr_combine} default to \code{"rename"}; \code{graph_attr_combine} defaults to +the \code{graph_attr_combine} igraph option (\code{"rename"} unless changed via \code{\link[=igraph_options]{igraph_options()}}). \code{"rename"} preserves the historical behaviour of appending \verb{_1}, \verb{_2}, ... suffixes. See \link{igraph-attribute-combination} for the available combiners.} @@ -49,8 +49,8 @@ of the internal numeric vertex IDs. \code{union()} keeps the attributes of all graphs. All graph, vertex and edge attributes are copied to the result. By default, if an attribute is present in multiple graphs and would result in a name clash, that attribute -is renamed by adding suffixes: \verb{_1}, \verb{_2}, etc. Pass \code{graph.attr.comb}, -\code{vertex.attr.comb} or \code{edge.attr.comb} to combine clashing attributes +is renamed by adding suffixes: \verb{_1}, \verb{_2}, etc. Pass \code{graph_attr_combine}, +\code{vertex_attr_combine} or \code{edge_attr_combine} to combine clashing attributes instead, e.g. by summing or by taking the first non-\code{NA} value. See \link{igraph-attribute-combination} for the available combiners. diff --git a/man/which_multiple.Rd b/man/which_multiple.Rd index 52f8c687398..f75623d3680 100644 --- a/man/which_multiple.Rd +++ b/man/which_multiple.Rd @@ -88,7 +88,7 @@ which_multiple(make_graph(c(1, 2, 2, 1), dir = FALSE)) # Remove multiple edges but keep multiplicity g <- sample_pa(10, m = 3, algorithm = "bag") E(g)$weight <- count_multiple(g) -g <- simplify(g, edge.attr.comb = list(weight = "min")) +g <- simplify(g, edge_attr_combine = list(weight = "min")) any(which_multiple(g)) E(g)$weight diff --git a/tests/testthat/_snaps/conversion.md b/tests/testthat/_snaps/conversion.md index dd796ca286b..7e39ca56ba6 100644 --- a/tests/testthat/_snaps/conversion.md +++ b/tests/testthat/_snaps/conversion.md @@ -17,6 +17,13 @@ Warning: `as.undirected()` was deprecated in igraph 2.1.0. i Please use `as_undirected()` instead. + Warning: + The igraph option `edge.attr.comb` was deprecated in igraph 3.0.0. + i Please use the `edge_attr_combine` option instead. + Warning: + Calling `as_undirected()` with positional or abbreviated arguments was deprecated in igraph 3.0.0. + i Detected call: as_undirected(graph, mode, edge.attr.comb) + i Use instead: as_undirected(graph, mode, edge_attr_combine = ) Output [1] FALSE diff --git a/tests/testthat/test-attributes.R b/tests/testthat/test-attributes.R index f46f03db367..b407cb5482a 100644 --- a/tests/testthat/test-attributes.R +++ b/tests/testthat/test-attributes.R @@ -214,11 +214,11 @@ test_that("attribute combinations handle errors correctly", { g <- make_graph(c(1, 2, 2, 1)) E(g)$weight <- c("a", "b") expect_error( - as_undirected(g, edge.attr.comb = list(weight = "sum")), + as_undirected(g, edge_attr_combine = list(weight = "sum")), "invalid 'type'" ) expect_error( - as_undirected(g, edge.attr.comb = list(weight = sum)), + as_undirected(g, edge_attr_combine = list(weight = sum)), "invalid 'type'" ) }) diff --git a/tests/testthat/test-community.R b/tests/testthat/test-community.R index 65183998533..952fba7f71f 100644 --- a/tests/testthat/test-community.R +++ b/tests/testthat/test-community.R @@ -646,7 +646,7 @@ test_that("contract works", { V(g)$name <- letters[1:vcount(g)] E(g)$weight <- sample(ecount(g)) - g2 <- contract(g, rep(1:5, each = 2), vertex.attr.comb = toString) + g2 <- contract(g, rep(1:5, each = 2), vertex_attr_combine = toString) expect_equal(g2$name, g$name) expect_equal(V(g2)$name, c("a, b", "c, d", "e, f", "g, h", "i, j")) diff --git a/tests/testthat/test-operators.R b/tests/testthat/test-operators.R index b79abf500b9..d96c7a9cbcc 100644 --- a/tests/testthat/test-operators.R +++ b/tests/testthat/test-operators.R @@ -1306,14 +1306,14 @@ test_that("union() defaults to rename behaviour", { test_that("union() combines vertex attributes with sum", { gs <- make_named_pair() - u <- union(gs$g1, gs$g2, vertex.attr.comb = "sum") + u <- union(gs$g1, gs$g2, vertex_attr_combine = "sum") expect_setequal(vertex_attr_names(u), c("name", "weight")) expect_equal(sort(V(u)$weight), sort(c(11, 22, 33))) }) test_that("union() combines edge attributes with sum", { gs <- make_named_pair() - u <- union(gs$g1, gs$g2, edge.attr.comb = "sum") + u <- union(gs$g1, gs$g2, edge_attr_combine = "sum") expect_setequal(edge_attr_names(u), c("weight")) expect_equal(sort(E(u)$weight), sort(c(11, 22, 33))) }) @@ -1325,7 +1325,7 @@ test_that("union() honours per-attribute list spec with rename fallback", { u <- union( gs$g1, gs$g2, - vertex.attr.comb = list(weight = "sum", "rename") + vertex_attr_combine = list(weight = "sum", "rename") ) expect_setequal( vertex_attr_names(u), @@ -1335,7 +1335,7 @@ test_that("union() honours per-attribute list spec with rename fallback", { test_that("union() can drop clashing attributes with ignore", { gs <- make_named_pair() - u <- union(gs$g1, gs$g2, edge.attr.comb = "ignore") + u <- union(gs$g1, gs$g2, edge_attr_combine = "ignore") expect_length(edge_attr_names(u), 0) }) @@ -1344,14 +1344,14 @@ test_that("union() supports custom function combiner", { u <- union( gs$g1, gs$g2, - vertex.attr.comb = list(weight = function(x) mean(x)) + vertex_attr_combine = list(weight = function(x) mean(x)) ) expect_equal(sort(V(u)$weight), sort(c(5.5, 11, 16.5))) }) test_that("union() picks first non-NA when only one input has the attr", { gs <- make_named_pair() - u <- union(gs$g1, gs$g2, vertex.attr.comb = "first", byname = TRUE) + u <- union(gs$g1, gs$g2, vertex_attr_combine = "first", byname = TRUE) expect_setequal(vertex_attr_names(u), c("name", "weight")) expect_equal( V(u)$weight[match(c("A", "B", "C"), V(u)$name)], @@ -1361,7 +1361,7 @@ test_that("union() picks first non-NA when only one input has the attr", { test_that("intersection() takes attr.comb args", { gs <- make_named_pair() - i <- intersection(gs$g1, gs$g2, edge.attr.comb = "sum") + i <- intersection(gs$g1, gs$g2, edge_attr_combine = "sum") expect_setequal(edge_attr_names(i), c("weight")) expect_equal(sort(E(i)$weight), sort(c(11, 22, 33))) }) @@ -1371,7 +1371,7 @@ test_that("compose() takes attr.comb args", { g2 <- graph_from_literal(A - B - E - A) V(g1)$foo <- seq_len(vcount(g1)) V(g2)$foo <- 10 * seq_len(vcount(g2)) - g <- compose(g1, g2, vertex.attr.comb = "sum") + g <- compose(g1, g2, vertex_attr_combine = "sum") expect_true("foo" %in% vertex_attr_names(g)) expect_false("foo_1" %in% vertex_attr_names(g)) }) @@ -1381,12 +1381,12 @@ test_that("disjoint_union() combines graph attrs via comb", { g2 <- make_ring(3) g1$label <- "first" g2$label <- "second" - u <- disjoint_union(g1, g2, graph.attr.comb = "concat") + u <- disjoint_union(g1, g2, graph_attr_combine = "concat") expect_equal(u$label, c("first", "second")) }) -test_that("graph.attr.comb defaults to the graph.attr.comb igraph option", { - expect_equal(igraph_opt("graph.attr.comb"), "rename") +test_that("graph_attr_combine defaults to the graph_attr_combine igraph option", { + expect_equal(igraph_opt("graph_attr_combine"), "rename") g1 <- make_ring(3) g2 <- make_ring(3) @@ -1398,7 +1398,7 @@ test_that("graph.attr.comb defaults to the graph.attr.comb igraph option", { expect_all_true(c("label_1", "label_2") %in% graph_attr_names(u)) # Setting the option changes the default for the graph operators. - local_igraph_options(graph.attr.comb = "ignore") + local_igraph_options(graph_attr_combine = "ignore") expect_length(graph_attr_names(union(g1, g2)), 0) expect_length(graph_attr_names(intersection(g1, g2)), 0) expect_length(graph_attr_names(disjoint_union(g1, g2)), 0) @@ -1409,7 +1409,7 @@ test_that("simplify() rejects 'rename' combiner", { g <- make_graph(c(1, 2, 1, 2, 1, 2, 2, 3, 3, 4)) E(g)$weight <- 1:5 expect_error( - simplify(g, edge.attr.comb = "rename"), + simplify(g, edge_attr_combine = "rename"), "rename" ) }) @@ -1445,9 +1445,9 @@ test_that("compose() takes all tail arguments by name", { g1, g2, byname = FALSE, - graph.attr.comb = "first", - vertex.attr.comb = "first", - edge.attr.comb = "concat" + graph_attr_combine = "first", + vertex_attr_combine = "first", + edge_attr_combine = "concat" ) # By vertex ID the graphs overlap; by name they are disjoint (6 vertices, no edge). @@ -1469,4 +1469,13 @@ test_that("compose() recovers legacy positional arguments", { res <- compose(g1, g2, FALSE) ) expect_identical_graphs(res, compose(g1, g2, byname = FALSE)) + + # The old dotted argument names are recovered from `...` and soft-deprecate. + lifecycle::expect_deprecated( + res_dotted <- compose(g1, g2, byname = FALSE, edge.attr.comb = "concat") + ) + expect_identical_graphs( + res_dotted, + compose(g1, g2, byname = FALSE, edge_attr_combine = "concat") + ) }) diff --git a/tools/migrations/attr-comb.R b/tools/migrations/attr-comb.R new file mode 100644 index 00000000000..bd08d76d8f0 --- /dev/null +++ b/tools/migrations/attr-comb.R @@ -0,0 +1,46 @@ +# Argument-signature migrations: attribute combination +# Schema: see tools/migrations/README.md. Regenerate with: +# Rscript tools/generate-migrations.R + +migrations <- list( + # Dotted `*.attr.comb` arguments renamed to snake_case. The old dotted names + # keep working (recovered from `...`) under a single soft-deprecation. + simplify = list( + old = function( + graph, + remove.multiple, + remove.loops, + edge.attr.comb = edge_attr_combine + ) {}, + new = function( + graph, + remove.multiple = TRUE, + remove.loops = TRUE, + ..., + edge_attr_combine = igraph_opt("edge_attr_combine") + ) {}, + when = "3.0.0" + ), + + as_undirected = list( + old = function(graph, mode, edge.attr.comb = edge_attr_combine) {}, + new = function( + graph, + mode = c("collapse", "each", "mutual"), + ..., + edge_attr_combine = igraph_opt("edge_attr_combine") + ) {}, + when = "3.0.0" + ), + + contract = list( + old = function(graph, mapping, vertex.attr.comb = vertex_attr_combine) {}, + new = function( + graph, + mapping, + ..., + vertex_attr_combine = igraph_opt("vertex_attr_combine") + ) {}, + when = "3.0.0" + ) +) diff --git a/tools/migrations/centrality.R b/tools/migrations/centrality.R index 45a7912fd1f..886ce649260 100644 --- a/tools/migrations/centrality.R +++ b/tools/migrations/centrality.R @@ -1,5 +1,5 @@ # Argument-signature migrations: centrality -# Schema: see tools/migrations.R. Regenerate with: +# Schema: see tools/migrations/README.md. Regenerate with: # Rscript tools/generate-migrations.R migrations <- list( diff --git a/tools/migrations/centralization.R b/tools/migrations/centralization.R index 0844a295b1b..3f7d94bcdf8 100644 --- a/tools/migrations/centralization.R +++ b/tools/migrations/centralization.R @@ -1,5 +1,5 @@ # Argument-signature migrations: centralization -# Schema: see tools/migrations.R. Regenerate with: +# Schema: see tools/migrations/README.md. Regenerate with: # Rscript tools/generate-migrations.R migrations <- list( diff --git a/tools/migrations/community.R b/tools/migrations/community.R index d8cb12bc310..a5d6afb3a9e 100644 --- a/tools/migrations/community.R +++ b/tools/migrations/community.R @@ -1,5 +1,5 @@ # Argument-signature migrations: community -# Schema: see tools/migrations.R. Regenerate with: +# Schema: see tools/migrations/README.md. Regenerate with: # Rscript tools/generate-migrations.R migrations <- list( diff --git a/tools/migrations/operators.R b/tools/migrations/operators.R index 219b04a5187..6f6cda3faee 100644 --- a/tools/migrations/operators.R +++ b/tools/migrations/operators.R @@ -18,18 +18,18 @@ migrations <- list( g1, g2, byname, - graph.attr.comb, - vertex.attr.comb, - edge.attr.comb + graph.attr.comb = graph_attr_combine, + vertex.attr.comb = vertex_attr_combine, + edge.attr.comb = edge_attr_combine ) {}, new = function( g1, g2, ..., byname = "auto", - graph.attr.comb = igraph_opt("graph.attr.comb"), - vertex.attr.comb = "rename", - edge.attr.comb = "rename" + graph_attr_combine = igraph_opt("graph_attr_combine"), + vertex_attr_combine = "rename", + edge_attr_combine = "rename" ) {}, when = "3.0.0" ), diff --git a/tools/migrations/structural-properties.R b/tools/migrations/structural-properties.R index 66294f77374..7c26a138144 100644 --- a/tools/migrations/structural-properties.R +++ b/tools/migrations/structural-properties.R @@ -1,5 +1,5 @@ # Argument-signature migrations: structural-properties -# Schema: see tools/migrations.R. Regenerate with: +# Schema: see tools/migrations/README.md. Regenerate with: # Rscript tools/generate-migrations.R migrations <- list( diff --git a/tools/stimulus/types-RR.yaml b/tools/stimulus/types-RR.yaml index bfb5ca69ed8..0594b749682 100644 --- a/tools/stimulus/types-RR.yaml +++ b/tools/stimulus/types-RR.yaml @@ -531,12 +531,12 @@ SUBGRAPH_IMPL: EDGE_ATTRIBUTE_COMBINATION: DEFAULT: - Default: igraph_opt("edge.attr.comb") + Default: igraph_opt("edge_attr_combine") INCONV: '%I% <- igraph.i.attribute.combination(%I%)' VERTEX_ATTRIBUTE_COMBINATION: DEFAULT: - Default: igraph_opt("vertex.attr.comb") + Default: igraph_opt("vertex_attr_combine") INCONV: '%I% <- igraph.i.attribute.combination(%I%)' ADD_WEIGHTS: