#' Centralization of a graph

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralize.scores()` was renamed to [centralize()] to create a more

#' consistent API.

#' @inheritParams centralize

#' @keywords internal

#' @export

centralize.scores <- function(scores, theoretical.max = 0, normalized = TRUE) {

# nocov start

lifecycle::deprecate_warn("2.0.0", "centralize.scores()", "centralize()")

centralize(

scores = scores,

theoretical.max = theoretical.max,

normalized = normalized

)

} # nocov end

#' Theoretical maximum for betweenness centralization

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.evcent.tmax()` was renamed to [centr_eigen_tmax()] to create a more

#' consistent API.

#' @inheritParams centr_eigen_tmax

#' @keywords internal

#' @export

centralization.evcent.tmax <- function(

graph = NULL,

nodes = 0,

directed = FALSE,

scale = TRUE

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.evcent.tmax()",

"centr_eigen_tmax()"

)

centr_eigen_tmax(

graph = graph,

nodes = nodes,

directed = directed,

scale = scale

)

} # nocov end

#' Centralize a graph according to the eigenvector centrality of vertices

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.evcent()` was renamed to [centr_eigen()] to create a more

#' consistent API.

#' @inheritParams centr_eigen

#' @keywords internal

#' @export

centralization.evcent <- function(

graph,

directed = FALSE,

scale = TRUE,

options = arpack_defaults(),

normalized = TRUE

) {

# nocov start

lifecycle::deprecate_warn("2.0.0", "centralization.evcent()", "centr_eigen()")

centr_eigen(

graph = graph,

directed = directed,

scale = scale,

options = options,

normalized = normalized

)

} # nocov end

#' Theoretical maximum for degree centralization

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.degree.tmax()` was renamed to [centr_degree_tmax()] to create a more

#' consistent API.

#' @inheritParams centr_degree_tmax

#' @keywords internal

#' @export

centralization.degree.tmax <- function(

graph = NULL,

nodes = 0,

mode = c("all", "out", "in", "total"),

loops = FALSE

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.degree.tmax()",

"centr_degree_tmax()"

)

centr_degree_tmax(graph = graph, nodes = nodes, mode = mode, loops = loops)

} # nocov end

#' Centralize a graph according to the degrees of vertices

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.degree()` was renamed to [centr_degree()] to create a more

#' consistent API.

#' @inheritParams centr_degree

#' @keywords internal

#' @export

centralization.degree <- function(

graph,

mode = c("all", "out", "in", "total"),

loops = TRUE,

normalized = TRUE

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.degree()",

"centr_degree()"

)

centr_degree(

graph = graph,

mode = mode,

loops = loops,

normalized = normalized

)

} # nocov end

#' Theoretical maximum for closeness centralization

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.closeness.tmax()` was renamed to [centr_clo_tmax()] to create a more

#' consistent API.

#' @inheritParams centr_clo_tmax

#' @keywords internal

#' @export

centralization.closeness.tmax <- function(

graph = NULL,

nodes = 0,

mode = c("out", "in", "all", "total")

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.closeness.tmax()",

"centr_clo_tmax()"

)

centr_clo_tmax(graph = graph, nodes = nodes, mode = mode)

} # nocov end

#' Centralize a graph according to the closeness of vertices

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.closeness()` was renamed to [centr_clo()] to create a more

#' consistent API.

#' @inheritParams centr_clo

#' @keywords internal

#' @export

centralization.closeness <- function(

graph,

mode = c("out", "in", "all", "total"),

normalized = TRUE

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.closeness()",

"centr_clo()"

)

centr_clo(graph = graph, mode = mode, normalized = normalized)

} # nocov end

#' Theoretical maximum for betweenness centralization

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.betweenness.tmax()` was renamed to [centr_betw_tmax()] to create a more

#' consistent API.

#' @inheritParams centr_betw_tmax

#' @keywords internal

#' @export

centralization.betweenness.tmax <- function(

graph = NULL,

nodes = 0,

directed = TRUE

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.betweenness.tmax()",

"centr_betw_tmax()"

)

centr_betw_tmax(graph = graph, nodes = nodes, directed = directed)

} # nocov end

#' Centralize a graph according to the betweenness of vertices

#'

#' @description

#' `r lifecycle::badge("deprecated")`

#'

#' `centralization.betweenness()` was renamed to [centr_betw()] to create a more

#' consistent API.

#' @inheritParams centr_betw

#' @keywords internal

#' @export

centralization.betweenness <- function(

graph,

directed = TRUE,

normalized = TRUE

) {

# nocov start

lifecycle::deprecate_warn(

"2.0.0",

"centralization.betweenness()",

"centr_betw()"

)

centr_betw(graph = graph, directed = directed, normalized = normalized)

} # nocov end

## -----------------------------------------------------------------------

##

## IGraph R package

## Copyright (C) 2015 Gabor Csardi <csardi.gabor@gmail.com>

## 334 Harvard street, Cambridge, MA 02139 USA

##

## This program is free software; you can redistribute it and/or modify

## it under the terms of the GNU General Public License as published by

## the Free Software Foundation; either version 2 of the License, or

## (at your option) any later version.

##

## This program is distributed in the hope that it will be useful,

## but WITHOUT ANY WARRANTY; without even the implied warranty of

## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

## GNU General Public License for more details.

##

## You should have received a copy of the GNU General Public License

## along with this program; if not, write to the Free Software

## Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA

## 02110-1301 USA

##

## -----------------------------------------------------------------------

NULL

#' Centralization of a graph

#'

#' Centralization is a method for creating a graph level centralization

#' measure from the centrality scores of the vertices.

#'

#' Centralization is a general method for calculating a graph-level

#' centrality score based on node-level centrality measure. The formula for

#' this is

#' \deqn{C(G)=\sum_v (\max_w c_w - c_v),}{ C(G)=sum(max(c(w), w) - c(v), v),}

#' where \eqn{c_v}{c(v)} is the centrality of vertex \eqn{v}.

#'

#' The graph-level centralization measure can be normalized by dividing by the

#' maximum theoretical score for a graph with the same number of vertices,

#' using the same parameters, e.g. directedness, whether we consider loop

#' edges, etc.

#'

#' For degree, closeness and betweenness the most centralized structure is

#' some version of the star graph, in-star, out-star or undirected star.

#'

#' For eigenvector centrality the most centralized structure is the graph

#' with a single edge (and potentially many isolates).

#'

#' `centralize()` implements general centralization formula to calculate

#' 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

#' to `TRUE`.

#' @param normalized Logical. Whether to normalize the graph level

#' centrality score by dividing by the supplied theoretical maximum.

#' @return A real scalar, the centralization of the graph from which

#' `scores` were derived.

#'

#' @aliases centralization

#' @family centralization related

#'

#' @export

#' @references Freeman, L.C. (1979). Centrality in Social Networks I:

#' Conceptual Clarification. *Social Networks* 1, 215--239.

#'

#' Wasserman, S., and Faust, K. (1994). *Social Network Analysis:

#' Methods and Applications.* Cambridge University Press.

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_degree(g)$centralization

#' centr_clo(g, mode = "all")$centralization

#' centr_eigen(g, directed = FALSE)$centralization

#'

#' # Calculate centralization from pre-computed scores

#' deg <- degree(g)

#' tmax <- centr_degree_tmax(g, loops = FALSE)

#' centralize(deg, tmax)

#'

#' # The most centralized graph according to eigenvector centrality

#' g0 <- make_graph(c(2, 1), n = 10, dir = FALSE)

#' g1 <- make_star(10, mode = "undirected")

#' centr_eigen(g0)$centralization

#' centr_eigen(g1)$centralization

centralize <- function(

scores,

...,

theoretical.max = 0,

normalized = TRUE

) {

# BEGIN GENERATED ARG_HANDLE: centralize, do not edit, see tools/generate-migrations.R

# fmt: skip

if (...length() > 0L) {

# Pre-3.0.0 signature: centralize(scores, theoretical.max, normalized)

.old_signature <- function(theoretical.max, normalized, ...) {

if (...length() > 0L) {

.arg_extra <- base::names(base::substitute(...()))

.arg_extra <- .arg_extra[base::nzchar(.arg_extra)]

if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn centralize}.", call = base::parent.frame())

cli::cli_abort(base::c("Unexpected argument passed to {.fn centralize}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())

}

base::c(

if (!base::missing(theoretical.max)) base::list(theoretical.max = theoretical.max),

if (!base::missing(normalized)) base::list(normalized = normalized)

)

}

.arg_handle <- .old_signature(...)

if (base::length(.arg_handle) > 0L) {

.arg_names <- base::names(.arg_handle)

.arg_conflict <- base::intersect(.arg_names, base::c(

if (!base::missing(theoretical.max)) "theoretical.max",

if (!base::missing(normalized)) "normalized"

))

if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn centralize} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))

base::list2env(.arg_handle, base::environment())

lifecycle::deprecate_soft(

"3.0.0",

what = base::I("Calling `centralize()` with positional or abbreviated arguments"),

details = base::c(

i = base::paste0("Detected call: centralize(", base::paste(base::c("scores", .arg_names), collapse = ", "), ")"),

i = base::paste0("Use instead: centralize(", base::paste(base::c("scores", base::paste0(.arg_names, " = ")), collapse = ", "), ")")

)

)

}

}

# END GENERATED ARG_HANDLE

centralization_impl(

scores = scores,

theoretical_max = theoretical.max,

normalized = normalized

)

}

#' Centralize a graph according to the degrees of vertices

#'

#' 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

#' calculating the degree.

#' @param normalized Logical. Whether to normalize the graph level

#' centrality score by dividing by the theoretical maximum.

#' @return A named list with the following components:

#' \describe{

#' \item{res}{

#' The node-level centrality scores.

#' }

#' \item{centralization}{

#' The graph level centrality index.

#' }

#' \item{theoretical_max}{

#' The maximum theoretical graph level centralization score

#' for a graph with the given number of vertices,

#' using the same parameters.

#' If the `normalized` argument was `TRUE`,

#' then the result was divided by this number.

#' }

#' }

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_degree(g)$centralization

#' centr_clo(g, mode = "all")$centralization

#' centr_betw(g, directed = FALSE)$centralization

#' 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

# fmt: skip

if (...length() > 0L) {

# Pre-3.0.0 signature: centr_degree(graph, mode, loops, normalized)

.old_signature <- function(mode, loops, normalized, ...) {

if (...length() > 0L) {

.arg_extra <- base::names(base::substitute(...()))

.arg_extra <- .arg_extra[base::nzchar(.arg_extra)]

if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn centr_degree}.", call = base::parent.frame())

cli::cli_abort(base::c("Unexpected argument passed to {.fn centr_degree}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())

}

base::c(

if (!base::missing(mode)) base::list(mode = mode),

if (!base::missing(loops)) base::list(loops = loops),

if (!base::missing(normalized)) base::list(normalized = normalized)

)

}

.arg_handle <- .old_signature(...)

if (base::length(.arg_handle) > 0L) {

.arg_names <- base::names(.arg_handle)

.arg_conflict <- base::intersect(.arg_names, base::c(

if (!base::missing(mode)) "mode",

if (!base::missing(loops)) "loops",

if (!base::missing(normalized)) "normalized"

))

if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn centr_degree} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))

base::list2env(.arg_handle, base::environment())

lifecycle::deprecate_soft(

"3.0.0",

what = base::I("Calling `centr_degree()` with positional or abbreviated arguments"),

details = base::c(

i = base::paste0("Detected call: centr_degree(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"),

i = base::paste0("Use instead: centr_degree(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")")

)

)

}

}

# END GENERATED ARG_HANDLE

centralization_degree_impl(

graph = graph,

mode = mode,

loops = loops,

normalized = normalized

)

}

#' Theoretical maximum for degree centralization

#'

#' See [centralize()] for a summary of graph centralization.

#'

#' @param graph The input graph. It can also be `NULL` if `nodes` is given.

#' @param nodes The number of vertices. This is ignored if the graph is given.

#' @param mode This is the same as the `mode` argument of `degree()`. Ignored

#' if `graph` is given and the graph is undirected.

#' @inheritParams centr_degree

#' @return Real scalar, the theoretical maximum (unnormalized) graph degree

#' centrality score for graphs with given order and other parameters.

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_degree(g, normalized = FALSE)$centralization %>%

#' `/`(centr_degree_tmax(g, loops = FALSE))

#' centr_degree(g, normalized = TRUE)$centralization

centr_degree_tmax <- function(

graph = NULL,

nodes = 0,

mode = c("all", "out", "in", "total"),

loops

) {

if (!lifecycle::is_present(loops)) {

lifecycle::deprecate_stop(

when = "2.0.0",

what = "centr_degree_tmax(loops = 'must be explicit')",

details = "The default value (currently `FALSE`) will be dropped in the next release. Add an explicit value for the `loops` argument."

)

}

# Argument checks

ensure_igraph(graph, optional = TRUE)

nodes <- as.numeric(nodes)

loops <- as.logical(loops)

# Function call

res <- centralization_degree_tmax_impl(

graph = graph,

nodes = nodes,

mode = mode,

loops = loops

)

res

}

#' Centralize a graph according to the betweenness of vertices

#'

#' 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

#' @return A named list with the following components:

#' \describe{

#' \item{res}{

#' The node-level centrality scores.

#' }

#' \item{centralization}{

#' The graph level centrality index.

#' }

#' \item{theoretical_max}{

#' The maximum theoretical graph level centralization score

#' for a graph with the given number of vertices,

#' using the same parameters.

#' If the `normalized` argument was `TRUE`,

#' then the result was divided by this number.

#' }

#' }

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_degree(g)$centralization

#' 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

) {

# BEGIN GENERATED ARG_HANDLE: centr_betw, do not edit, see tools/generate-migrations.R

# fmt: skip

if (...length() > 0L) {

# Pre-3.0.0 signature: centr_betw(graph, directed, normalized)

.old_signature <- function(directed, normalized, ...) {

if (...length() > 0L) {

.arg_extra <- base::names(base::substitute(...()))

.arg_extra <- .arg_extra[base::nzchar(.arg_extra)]

if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn centr_betw}.", call = base::parent.frame())

cli::cli_abort(base::c("Unexpected argument passed to {.fn centr_betw}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())

}

base::c(

if (!base::missing(directed)) base::list(directed = directed),

if (!base::missing(normalized)) base::list(normalized = normalized)

)

}

.arg_handle <- .old_signature(...)

if (base::length(.arg_handle) > 0L) {

.arg_names <- base::names(.arg_handle)

.arg_conflict <- base::intersect(.arg_names, base::c(

if (!base::missing(directed)) "directed",

if (!base::missing(normalized)) "normalized"

))

if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn centr_betw} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))

base::list2env(.arg_handle, base::environment())

lifecycle::deprecate_soft(

"3.0.0",

what = base::I("Calling `centr_betw()` with positional or abbreviated arguments"),

details = base::c(

i = base::paste0("Detected call: centr_betw(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"),

i = base::paste0("Use instead: centr_betw(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")")

)

)

}

}

# END GENERATED ARG_HANDLE

# Argument checks

ensure_igraph(graph)

directed <- as.logical(directed)

normalized <- as.logical(normalized)

# Function call

res <- centralization_betweenness_impl(

graph = graph,

directed = directed,

normalized = normalized

)

res

}

#' Theoretical maximum for betweenness centralization

#'

#' See [centralize()] for a summary of graph centralization.

#'

#' @param graph The input graph. It can also be `NULL` if

#' `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.

#' @return Real scalar, the theoretical maximum (unnormalized) graph

#' betweenness centrality score for graphs with given order and other

#' parameters.

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' 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

) {

# BEGIN GENERATED ARG_HANDLE: centr_betw_tmax, do not edit, see tools/generate-migrations.R

# fmt: skip

if (...length() > 0L) {

# Pre-3.0.0 signature: centr_betw_tmax(graph, nodes, directed)

.old_signature <- function(directed, ...) {

if (...length() > 0L) {

.arg_extra <- base::names(base::substitute(...()))

.arg_extra <- .arg_extra[base::nzchar(.arg_extra)]

if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn centr_betw_tmax}.", call = base::parent.frame())

cli::cli_abort(base::c("Unexpected argument passed to {.fn centr_betw_tmax}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())

}

base::c(

if (!base::missing(directed)) base::list(directed = directed)

)

}

.arg_handle <- .old_signature(...)

if (base::length(.arg_handle) > 0L) {

.arg_names <- base::names(.arg_handle)

.arg_conflict <- base::intersect(.arg_names, base::c(

if (!base::missing(directed)) "directed"

))

if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn centr_betw_tmax} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))

base::list2env(.arg_handle, base::environment())

lifecycle::deprecate_soft(

"3.0.0",

what = base::I("Calling `centr_betw_tmax()` with positional or abbreviated arguments"),

details = base::c(

i = base::paste0("Detected call: centr_betw_tmax(", base::paste(base::c("graph", "nodes", .arg_names), collapse = ", "), ")"),

i = base::paste0("Use instead: centr_betw_tmax(", base::paste(base::c("graph", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")")

)

)

}

}

# END GENERATED ARG_HANDLE

centralization_betweenness_tmax_impl(

graph = graph,

nodes = nodes,

directed = directed

)

}

#' Centralize a graph according to the closeness of vertices

#'

#' 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

#' @return A named list with the following components:

#' \describe{

#' \item{res}{

#' The node-level centrality scores.

#' }

#' \item{centralization}{

#' The graph level centrality index.

#' }

#' \item{theoretical_max}{

#' The maximum theoretical graph level centralization score

#' for a graph with the given number of vertices,

#' using the same parameters.

#' If the `normalized` argument was `TRUE`,

#' then the result was divided by this number.

#' }

#' }

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_degree(g)$centralization

#' centr_clo(g, mode = "all")$centralization

#' centr_betw(g, directed = FALSE)$centralization

#' 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

# fmt: skip

if (...length() > 0L) {

# Pre-3.0.0 signature: centr_clo(graph, mode, normalized)

.old_signature <- function(mode, normalized, ...) {

if (...length() > 0L) {

.arg_extra <- base::names(base::substitute(...()))

.arg_extra <- .arg_extra[base::nzchar(.arg_extra)]

if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn centr_clo}.", call = base::parent.frame())

cli::cli_abort(base::c("Unexpected argument passed to {.fn centr_clo}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())

}

base::c(

if (!base::missing(mode)) base::list(mode = mode),

if (!base::missing(normalized)) base::list(normalized = normalized)

)

}

.arg_handle <- .old_signature(...)

if (base::length(.arg_handle) > 0L) {

.arg_names <- base::names(.arg_handle)

.arg_conflict <- base::intersect(.arg_names, base::c(

if (!base::missing(mode)) "mode",

if (!base::missing(normalized)) "normalized"

))

if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn centr_clo} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))

base::list2env(.arg_handle, base::environment())

lifecycle::deprecate_soft(

"3.0.0",

what = base::I("Calling `centr_clo()` with positional or abbreviated arguments"),

details = base::c(

i = base::paste0("Detected call: centr_clo(", base::paste(base::c("graph", .arg_names), collapse = ", "), ")"),

i = base::paste0("Use instead: centr_clo(", base::paste(base::c("graph", base::paste0(.arg_names, " = ")), collapse = ", "), ")")

)

)

}

}

# END GENERATED ARG_HANDLE

centralization_closeness_impl(

graph = graph,

mode = mode,

normalized = normalized

)

}

#' Theoretical maximum for closeness centralization

#'

#' See [centralize()] for a summary of graph centralization.

#'

#' @param graph The input graph. It can also be `NULL` if

#' `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

#' closeness centrality score for graphs with given order and other

#' parameters.

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_clo(g, normalized = FALSE)$centralization %>%

#' `/`(centr_clo_tmax(g))

#' centr_clo(g, normalized = TRUE)$centralization

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

# fmt: skip

if (...length() > 0L) {

# Pre-3.0.0 signature: centr_clo_tmax(graph, nodes, mode)

.old_signature <- function(mode, ...) {

if (...length() > 0L) {

.arg_extra <- base::names(base::substitute(...()))

.arg_extra <- .arg_extra[base::nzchar(.arg_extra)]

if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn centr_clo_tmax}.", call = base::parent.frame())

cli::cli_abort(base::c("Unexpected argument passed to {.fn centr_clo_tmax}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())

}

base::c(

if (!base::missing(mode)) base::list(mode = mode)

)

}

.arg_handle <- .old_signature(...)

if (base::length(.arg_handle) > 0L) {

.arg_names <- base::names(.arg_handle)

.arg_conflict <- base::intersect(.arg_names, base::c(

if (!base::missing(mode)) "mode"

))

if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn centr_clo_tmax} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))

base::list2env(.arg_handle, base::environment())

lifecycle::deprecate_soft(

"3.0.0",

what = base::I("Calling `centr_clo_tmax()` with positional or abbreviated arguments"),

details = base::c(

i = base::paste0("Detected call: centr_clo_tmax(", base::paste(base::c("graph", "nodes", .arg_names), collapse = ", "), ")"),

i = base::paste0("Use instead: centr_clo_tmax(", base::paste(base::c("graph", "nodes", base::paste0(.arg_names, " = ")), collapse = ", "), ")")

)

)

}

}

# END GENERATED ARG_HANDLE

centralization_closeness_tmax_impl(

graph = graph,

nodes = nodes,

mode = mode

)

}

#' Centralize a graph according to the eigenvector centrality of vertices

#'

#' See [centralize()] for a summary of graph centralization.

#'

#' @param graph The input graph.

#' @param directed Logical, whether to use directed shortest paths for

#' calculating eigenvector centrality.

#' @param scale `r lifecycle::badge("deprecated")` Ignored. Computing

#' eigenvector centralization requires normalized eigenvector centrality scores.

#' @param options This is passed to [eigen_centrality()], the options

#' for the ARPACK eigensolver.

#' @inheritParams centr_degree

#' @return A named list with the following components:

#' \describe{

#' \item{vector}{

#' The node-level centrality scores.

#' }

#' \item{value}{

#' The corresponding eigenvalue.

#' }

#' \item{options}{

#' ARPACK options, see the return value of [eigen_centrality()] for details.

#' }

#' \item{centralization}{

#' The graph level centrality index.

#' }

#' \item{theoretical_max}{

#' The same as above, the theoretical maximum centralization score

#' for a graph with the same number of vertices.

#' }

#' }

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_degree(g)$centralization

#' centr_clo(g, mode = "all")$centralization

#' centr_betw(g, directed = FALSE)$centralization

#' centr_eigen(g, directed = FALSE)$centralization

#'

#' # The most centralized graph according to eigenvector centrality

#' g0 <- make_graph(c(2, 1), n = 10, dir = FALSE)

#' g1 <- make_star(10, mode = "undirected")

#' centr_eigen(g0)$centralization

#' centr_eigen(g1)$centralization

centr_eigen <- function(

graph,

directed = FALSE,

scale = deprecated(),

options = arpack_defaults(),

normalized = TRUE

) {

if (lifecycle::is_present(scale)) {

lifecycle::deprecate_warn(

"2.2.0",

"centr_eigen(scale = )",

details = "The function always behaves as if `scale = TRUE`.

The argument will be removed in the future."

)

}

centralization_eigenvector_centrality_impl(

graph = graph,

directed = directed,

scale = TRUE,

options = options,

normalized = normalized

)

}

#' Theoretical maximum for eigenvector centralization

#'

#' See [centralize()] for a summary of graph centralization.

#'

#' @param graph The input graph. It can also be `NULL`, if

#' `nodes` is given.

#' @param nodes The number of vertices. This is ignored if the graph is

#' given.

#' @param directed Logical, whether to consider edge directions

#' during the calculation. Ignored in undirected graphs.

#' @param scale `r lifecycle::badge("deprecated")` Ignored. Computing

#' eigenvector centralization requires normalized eigenvector centrality scores.

#' @return Real scalar, the theoretical maximum (unnormalized) graph

#' eigenvector centrality score for graphs with given vertex count and

#' other parameters.

#'

#' @family centralization related

#'

#' @export

#'

#' @examples

#' # A BA graph is quite centralized

#' g <- sample_pa(1000, m = 4)

#' centr_eigen(g, normalized = FALSE)$centralization %>%

#' `/`(centr_eigen_tmax(g))

#' centr_eigen(g, normalized = TRUE)$centralization

centr_eigen_tmax <- function(

graph = NULL,

nodes = 0,

directed = FALSE,

scale = deprecated()

) {

if (lifecycle::is_present(scale)) {

lifecycle::deprecate_warn(

"2.2.0",

"centr_eigen_tmax(scale = )",

details = "The function always behaves as if `scale = TRUE`.

The argument will be removed in the future."

)

}

centralization_eigenvector_centrality_tmax_impl(

graph = graph,

nodes = nodes,

directed = directed,

scale = TRUE

)

}